@intellectif/lk-core 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @intellectif/lk-core
 
+## 1.2.0
+
+### Minor Changes
+
+- [#88](https://github.com/intellectif/learning-kit/pull/88) [`493dd06`](https://github.com/intellectif/learning-kit/commit/493dd0648a73c7f47d889683bc9f7f08d8a0acc9) Thanks [@diego28e](https://github.com/diego28e)! - **Assistants for authors**: an item critic, a model's review of an item, and drafts from a passage, a transcript or a video's captions.
+
+  **Action required:** none unless your code switches over `AiRefusal` without a `default` branch (new member `'contradicts-item'`) or reads `AiCheckCase.request` without narrowing on `feature` (new `'item-critique'` and `'draft-generation'` cases). Nothing runs until you call it, no grade changes, and there is no lk-react release: lk-react 23.1 works with it as it is. See https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md
+
+  - **The item critic:** `critiqueDraft(type, draft)`, `critiqueDrafts(entries)` for a question set and `critiqueItemGroupDraft(group)` for a testlet point out what a reviewer would on an item that may be perfectly valid — a title, hint or passage that prints the answer, two options that read the same, the right option much longer than the rest, "all of the above" under shuffle, a word bank with no distractor, a text too long for its recording time, every right option in one position. Findings are `warning` or `advice`, in `DraftIssue`'s shape so an editor lists both, and never change what `validateDraft` says. Seventeen codes, documented with their rules: https://github.com/intellectif/learning-kit/blob/main/docs/authoring.md
+  - **A registered type** joins the critic through a new optional `authoring.critique`.
+  - **A model's review:** `aiCritiqueRequest` gives a model the item, every text field it may point at, and the critic's own findings; `checkAiCritique` lists its findings as `advice`, and refuses the whole reply as `contradicts-item` when a finding points at a field the item does not have or quotes words that field does not hold.
+  - **Drafts from a source:** `aiDraftsRequest` takes the types an author ticks — multiple choice, fill in the blanks, gap select, dictation, read-aloud, written response — in the author's order, an optional count (left out, as many as the source is worth, up to 50), the author's own instructions and your settings per type, and gives the model the JSON Schema of a reply: each type's own fields, no ids, HTML, media, switches or scoring settings; `checkAiDrafts` makes drafts with your ids and settings, in the author's order, each checked by `validateDraft` and the critic — from captions placed where its caption ends, a dictation with the stretch of video that says it; `aiDraftsRepairRequest` sends back what is unfinished, wrong or warned about; `generateDrafts` runs that loop, once by default and three times at most, and never throws for a model's failure. A draft is never approved by the SDK. https://github.com/intellectif/learning-kit/blob/main/docs/ai.md
+  - **A video's quizzes:** `interactiveVideoFromDrafts` makes the drafts an interactive video — each question where its caption ends, questions at one moment in the author's order, and every question without a moment in one quiz at the end of the video (`durationSeconds`).
+  - **ai-check:** a `critique` port runs four review cases and a `drafts` port six drafting cases, two of them video quizzes.
+
+## 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

@@ -19,6 +19,7 @@ npm install @intellectif/lk-core
 - **`validateActivity(type, data)`** — the authoritative runtime validator. Returns a typed `{ success, data }` or a structured `{ success: false, errors[] }`, and **throws `UnknownActivityTypeError` if `type` is not registered** — so guard it when validating a content bank that may carry types this build does not know. `validateItemGroup(data)` is the equivalent for a `Stimulus` + `ItemGroup` container, which `validateActivity` cannot take.
 - **`validateDraft(type, draft)`** — for editors. Reports `complete`, `incomplete` (something not written yet) or `invalid` (something wrong), each issue with a `severity` and a `code` — documented for every problem the checks recognise — and deliberately no `success` boolean to misread. Stricter than `validateActivity`, never looser. **`createDraft(type, { newId })`** returns an empty draft to start from; a multiple-choice draft marks no option correct.
 - **An open type system** — `defineActivityType` / `registerActivityType` make an activity type a *value*, not a hard-coded union member: register one and `validateActivity`, `validateDraft`, `score`, `evaluate`, `redact` and `jsonSchemaFor` all work for it, with no SDK release. An `authoring` block on the descriptor gives it draft support.
+- **An item critic** — `critiqueDraft(type, draft)` (and `critiqueDrafts` for a question set, `critiqueItemGroupDraft` for a testlet) points out what a reviewer would on an item that may be perfectly valid: the right option much longer than the rest, an answer printed in the passage, a hint that gives it away, "all of the above" under shuffle. A finding is `warning` or `advice`, in `DraftIssue`'s shape, and never refuses an item.
 - **JSON Schema (Draft-7) export** — `jsonSchemaFor(type)` for any registered type (plus the static per-type exports), suitable for form generators or AI prompting.
 - **Scoring engine** — `score(activityType, data, response)` returning `{ score ∈ [0,1], maxScore: 1, passed, feedback, details }`. Pure, deterministic, 100 % test coverage enforced. It **throws** rather than inventing a number: `DeferredScoringError` for a deferred-graded type (`written-response`), and `RedactedScoringError` when handed a `redact()` projection, which has no answer key. Both are on the documented exam path — use `evaluate()` there, which returns `deferred` / `unscorable` instead of throwing.
 - **Dictation marking as data** — a dictation is graded by the character-level similarity of the typed text to the transcript, with one `ScoringDetail` per word carrying its own `score`. `alignDictation(data, text)` returns the same comparison the grade was made of (normalised strings, word pairings, which accepted transcript won), `diffDictationChars(reference, attempt)` the character-level edits for a marked display, and `dictationReferenceWords(data)` the ids and words a stored result can be checked against — so a review screen or an analytics job never re-implements the arithmetic. `score()` and `evaluate()` take an optional `{ rounding }` to compare the pass line as displayed.
@@ -28,7 +29,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. For authors, `aiCritiqueRequest` / `checkAiCritique` give a model's review of an item, whose every finding must point at the item's own fields, and `aiDraftsRequest` / `checkAiDrafts` / `generateDrafts` draft the types an author ticks, in the author's order, from a passage, a script or captions — each checked by `validateDraft`, critiqued, repaired in a bounded loop, and never approved by the SDK — and `interactiveVideoFromDrafts` makes them a video's quizzes, each question where its caption ends or at the end.
 - **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-D705CXng.d.cts}

@@ -63,6 +63,81 @@ declare function levenshteinDistance(a: string, b: string, max: number): number;
  */
 declare function matchText(input: string, accepted: string | readonly string[], policy?: TextMatchPolicy): TextMatchResult;
 
+/**
+ * Why a draft is not an activity yet.
+ *
+ * - `incomplete` — something the author has not written yet: an empty title, an
+ *   option with no text, no option marked correct. The fix is to add it.
+ * - `invalid` — something is wrong in a way that writing more cannot fix: two
+ *   correct options on a single-selection question, a maximum word count below
+ *   the minimum, a media address with a scheme the SDK refuses, a `null` in an
+ *   optional field that accepts none. The fix is to change it.
+ */
+type DraftSeverity = 'incomplete' | 'invalid';
+/**
+ * One problem with a draft. A {@link ValidationError} with a severity, so code
+ * that already lists `validateActivity` errors can list these unchanged.
+ */
+interface DraftIssue extends ValidationError {
+    severity: DraftSeverity;
+}
+/** A draft that is a valid activity and has nothing left to write. */
+interface DraftComplete<T> {
+    status: 'complete';
+    /** The validated activity, exactly as `validateActivity` returns it. */
+    data: T;
+    /** Always empty. Present so that every result can be read the same way. */
+    issues: DraftIssue[];
+}
+/**
+ * A draft that is not an activity yet: `invalid` when any issue is invalid,
+ * otherwise `incomplete`. It carries no `data`, because nothing here may be
+ * stored or rendered as an activity.
+ */
+interface DraftNotComplete {
+    status: 'incomplete' | 'invalid';
+    issues: DraftIssue[];
+}
+/**
+ * The result of `validateDraft`.
+ *
+ * There is deliberately no `success` boolean. A boolean has to call an
+ * incomplete draft either a success, which lets a half-written answer key
+ * through anything that checks it, or a failure, which is the conflation this
+ * result exists to remove. Branch on `status`.
+ */
+type DraftValidationResult<T> = DraftComplete<T> | DraftNotComplete;
+/**
+ * How much a finding of the item critic matters. Neither makes a draft
+ * incomplete or invalid: an item with findings is a valid item, stored and
+ * served like any other, and whether to change it is the author's call.
+ *
+ * - `warning` — a known flaw a learner can exploit or trip over: the right
+ *   option is the longest, an answer printed in the passage, a hint that gives
+ *   the answer away, two options that read the same.
+ * - `advice` — an item-writing guideline the item departs from: "all of the
+ *   above", two accepted answers the matcher already treats as one.
+ */
+type ItemFindingSeverity = 'warning' | 'advice';
+/**
+ * One thing the item critic found. A {@link ValidationError} with a severity,
+ * as a {@link DraftIssue} is, so an editor lists both in one list — sorted by
+ * severity: `invalid`, `incomplete`, `warning`, `advice`.
+ */
+interface ItemFinding extends ValidationError {
+    severity: ItemFindingSeverity;
+}
+/** What `createDraft` hands an activity type's `authoring.createDraft`. */
+interface DraftContext {
+    /**
+     * Returns a new id on every call. The SDK invents none: an id made here would
+     * need `crypto`, which plain-http origins do not have, or would be positional —
+     * and option ids reach the learner, so ids like `"a"` and `"b"` would tell them
+     * which option was written first.
+     */
+    newId: () => string;
+}
+
 /**
  * The return trip for deferred grading.
  *
@@ -226,8 +301,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 +323,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 +486,12 @@ 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.
+ * `contradicts-item` is a critique of an item that points at a field the item
+ * does not have, or quotes words that field does not contain.
  */
-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' | 'contradicts-item';
 /** One criterion of a written response's rubric, as the author wrote it. */
 interface AiRubricCriterionFact {
     name: string;
@@ -519,6 +597,355 @@ 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;
+}
+/**
+ * What a model may find wrong with an item, in the SDK's words:
+ *
+ * - `ambiguous` — a stem, passage or blank that reads two ways;
+ * - `second-answer` — a distractor that is defensibly right, or an answer the
+ *   key does not accept;
+ * - `wrong-key` — the answer marked right is not;
+ * - `implausible-distractor` — an option nobody who read the question would pick;
+ * - `cue` — grammar or wording that points at the answer;
+ * - `level` — language above or below the level the item is for;
+ * - `language` — a mistake in the item's own language;
+ * - `sensitivity` — content a learner may find loaded or unfamiliar for
+ *   reasons that have nothing to do with what is assessed;
+ * - `other`.
+ */
+type AiCritiqueKind = 'ambiguous' | 'second-answer' | 'wrong-key' | 'implausible-distractor' | 'cue' | 'level' | 'language' | 'sensitivity' | 'other';
+/** One field of an item a critique may point at, and what it says. */
+interface AiCritiqueField {
+    path: string[];
+    text: string;
+}
+/**
+ * What a host's model is given to review an item. Built by
+ * `aiCritiqueRequest`; for an author, never a learner, so it carries the
+ * answer key.
+ */
+interface AiCritiqueRequest {
+    feature: 'item-critique';
+    facts: {
+        activityType: string;
+        /** The item as the author wrote it, answer key included. */
+        item: Readonly<Record<string, unknown>>;
+        /** Every text field a finding may point at, with its text: the only paths a finding may name. */
+        fields: AiCritiqueField[];
+        /**
+         * What the SDK's own critic already found, so a model does not say it
+         * again: code, path and message.
+         */
+        findings: {
+            path: string[];
+            code: string;
+            message: string;
+        }[];
+        /** The level the item is for, as the host names it (`A2`, `B1`), when it gave one. */
+        level?: string;
+    };
+    /** The language to write findings in: the author's. */
+    authorLocale?: string;
+}
+/** One finding as a host's port returns it. */
+interface AiCritiqueFindingResult {
+    /** A path from `facts.fields`, exactly. */
+    path: (string | number)[];
+    kind: AiCritiqueKind;
+    /** What is wrong, and what to do, addressed to the author. */
+    message: string;
+    /** Words copied from that field, when the finding is about some of them. */
+    quote?: string;
+}
+/** What a host's critique port returns. */
+interface AiCritiqueResult {
+    findings: AiCritiqueFindingResult[];
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
+/**
+ * A model's finding, as the SDK accepted it: an `ItemFinding` — always
+ * `advice`, since it is a model's opinion — whose code is `ai_` and the kind
+ * (`ai_second_answer`), with the quote it pointed at.
+ */
+interface AiCritiqueFinding extends ItemFinding {
+    severity: 'advice';
+    quote?: string;
+}
+/** A critique, as the SDK accepted it. */
+interface AiCritique {
+    findings: AiCritiqueFinding[];
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
+/**
+ * The types a model can draft from a source. An interactive video takes the
+ * first five; a written response is for a quiz of its own.
+ */
+type AiDraftType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation' | 'read-aloud' | 'written-response';
+/**
+ * What drafts are written from: a passage or a script as text — an item
+ * group's `stimulus.transcript` is one — or a video's captions, each with its
+ * start and end in seconds, so a question can be placed where its caption ends.
+ */
+type AiDraftSource = {
+    kind: 'passage' | 'transcript';
+    text: string;
+} | {
+    kind: 'captions';
+    cues: {
+        start: number;
+        end: number;
+        text: string;
+    }[];
+};
+/** A caption as a model is given it: numbered, so a draft can name the one it is about. */
+interface AiDraftCaption {
+    index: number;
+    start: number;
+    end: number;
+    text: string;
+}
+/** One problem with a draft, as a model is told it on a repair. */
+interface AiDraftProblem {
+    path: string[];
+    code: string;
+    message: string;
+    severity: 'incomplete' | 'invalid' | 'warning';
+}
+/**
+ * Fields of the host's for every draft of a type — settings a model never
+ * writes: a read-aloud's `recording`, `scoring` and region-tagged `locale`, a
+ * question's `shuffle` or `scoringStrategy`. They are put on each draft of
+ * that type before it is checked, and never override what the model wrote, nor
+ * the draft's `id`, `type` or `schemaVersion`.
+ */
+type AiDraftSettings = Partial<Record<AiDraftType, Readonly<Record<string, unknown>>>>;
+/**
+ * What a host's model is given to draft items. Built by `aiDraftsRequest`, and
+ * by `aiDraftsRepairRequest` for a second pass over the drafts that came back
+ * unfinished or flawed in ways the model can fix.
+ */
+interface AiDraftsRequest {
+    feature: 'draft-generation';
+    facts: {
+        /**
+         * The types the author chose, in the author's order: the ones to lean on
+         * first, and the order questions are shown in where several share a moment
+         * of a video — or share the end of one.
+         */
+        activityTypes: AiDraftType[];
+        source: {
+            kind: 'passage' | 'transcript';
+            text: string;
+        } | {
+            kind: 'captions';
+            captions: AiDraftCaption[];
+        };
+        /** How many drafts to write, at most. Absent: as many as the source is worth, up to `AI_DRAFTS_MAX_COUNT`. */
+        count?: number;
+        /** The language the items are written in. */
+        locale?: string;
+        /** The level they are for, as the host names it (`A2`, `B1`). */
+        level?: string;
+        /** What the author asked for, in their words. */
+        instructions?: string;
+    };
+    /**
+     * The JSON Schema of a reply — `{ drafts: [...] }` — for a model's structured
+     * output, or its prompt. Plain JSON Schema a model can follow: types, required
+     * fields, enums and descriptions, nothing a provider's structured output
+     * commonly refuses. Each draft names its `type`, and fills the fields that
+     * type uses.
+     */
+    shape: Readonly<Record<string, unknown>>;
+    /** The host's settings for every draft of a type. Not for the model; `checkAiDrafts` applies them. */
+    settings?: AiDraftSettings;
+    /**
+     * On a repair: the drafts to fix, each as the model wrote it, with what is
+     * wrong with it that the model can fix. The reply holds one draft for each,
+     * in this order.
+     */
+    repair?: {
+        index: number;
+        draft: Readonly<Record<string, unknown>>;
+        problems: AiDraftProblem[];
+    }[];
+}
+/** A draft as the SDK made it from a reply: ids minted, settings applied, checked, and critiqued. */
+interface AiGeneratedDraft {
+    /** Its position in the first reply; a repaired draft keeps the position it replaces. */
+    index: number;
+    type: AiDraftType;
+    /** The draft, an activity of its type once `validation` says `complete`. */
+    draft: Record<string, unknown>;
+    /** What `validateDraft` says of it. `complete` means valid — never approved. */
+    validation: DraftValidationResult<unknown>;
+    /** What the item critic says of it. */
+    findings: ItemFinding[];
+    /**
+     * From captions: where the question goes, in seconds — the end of the
+     * caption it named. Absent when it named no caption the source has: it
+     * belongs at the end of the video.
+     */
+    at?: number;
+    /**
+     * A dictation from captions whose transcript is words of the caption it
+     * named: that caption's start and end, in seconds — the stretch of the
+     * video that says it, for a host that cuts the recording from the video.
+     */
+    clip?: {
+        start: number;
+        end: number;
+    };
+    /** The draft as the model wrote it, for a repair. */
+    generated: Readonly<Record<string, unknown>>;
+}
+/** What `checkAiDrafts` makes of a reply. */
+interface AiDrafts {
+    /** The drafts in the author's order of types, and in the order the model wrote them within a type. */
+    drafts: AiGeneratedDraft[];
+    /** What only the set shows: every right option in one place (`set_key_position_same`). */
+    findings: ItemFinding[];
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
+/** One call `generateDrafts` made: what it cost, or why it went no further. */
+type AiDraftsCall = {
+    ok: true;
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+} | {
+    ok: false;
+    refusal?: AiRefusal;
+    error?: string;
+};
+/** What `generateDrafts` came to. */
+interface AiDraftsRun {
+    /** The drafts, in the author's order of types, each the best pass of it. */
+    drafts: AiGeneratedDraft[];
+    /** What only the set shows, over the drafts as they ended. */
+    findings: ItemFinding[];
+    /** Every call, in order: the first, then each repair. */
+    calls: AiDraftsCall[];
+}
+/**
+ * An interactive video made of drafts: an item group whose stimulus is the
+ * video and whose timeline opens a quiz at each moment a draft was placed —
+ * and one at the end for every draft placed nowhere. A draft, like every
+ * draft: checked, critiqued, and approved by a person, never by the SDK.
+ */
+interface AiVideoDraft {
+    /** The item group, an interactive video once `validation` says `complete`. */
+    group: Record<string, unknown>;
+    /** What `validateItemGroupDraft` says of it. */
+    validation: DraftValidationResult<unknown>;
+    /** What `critiqueItemGroupDraft` says of it. */
+    findings: ItemFinding[];
+}
 
 /**
  * An xAPI Activity object — the thing a statement is about.
@@ -1714,7 +2141,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 +2159,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 AiWritingCorrection as $, type ActivityAiPermissions as A, type AiDrafts as B, type AiDraftsCall as C, type AiDraftsRequest as D, type AiDraftsRun as E, type AiExplanationRequest as F, type AiFeature as G, type AiFillInTheBlanksFacts as H, type AiGapFact as I, type AiGapSelectFacts as J, type AiGeneratedDraft as K, type AiGrade as L, type AiHintRequest as M, type AiItemFacts as N, type AiMultipleChoiceFacts as O, type AiOptionFact as P, type AiProvenance as Q, type AiReadingFacts as R, type AiReadingWordFact as S, type AiRefusal as T, type AiRubricCriterionFact as U, type AiSoundFact as V, type AiSupportedActivityType as W, type AiTextResult as X, type AiVerdict as Y, type AiVideoDraft as Z, type AiWordFact as _, type ActivityData as a, type WrittenResponseRubricCriterion as a$, type AiWritingFacts as a0, type AiWritingFeedback as a1, type AiWritingFeedbackRequest as a2, type AiWritingFeedbackResult as a3, type BlankConfig as a4, type CriterionScore as a5, type DeferredReason as a6, type DeferredScoringPartial as a7, type DictationData as a8, type DictationEquivalence as a9, 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 WrittenResponseRubric as a_, type DictationLearnerResponse as aa, type DictationSlowMedia as ab, type DictationTolerance as ac, type DraftComplete as ad, type DraftContext as ae, type DraftIssue as af, type DraftNotComplete as ag, type DraftSeverity as ah, type DraftValidationResult as ai, type FillInTheBlanksData as aj, type FillInTheBlanksLearnerResponse as ak, type GapSelectBank as al, type GapSelectChoice as am, type GapSelectData as an, type GapSelectGap as ao, type GapSelectLearnerResponse as ap, type GradeRecord as aq, type Grader as ar, type GraderKind as as, type GraderUsage as at, type GradingState as au, type InlineCorrection as av, type InteractionEvent as aw, type InteractionKind as ax, type ItemFinding as ay, type ItemFindingSeverity as az, type ActivityDataMap as b, type XAPIActor as b0, type XAPIConfig as b1, type XAPIContext as b2, type XAPIContextActivities as b3, type XAPIError as b4, type XAPIObject as b5, type XAPIResult as b6, type XAPIScore as b7, type XAPIStatement as b8, type XAPIVerbObject as b9, levenshteinDistance as ba, matchText as bb, 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 AiCritique as n, type AiCritiqueField as o, type AiCritiqueFinding as p, type AiCritiqueFindingResult as q, type AiCritiqueKind as r, type AiCritiqueRequest as s, type AiCritiqueResult as t, type AiDictationFacts as u, type AiDraftCaption as v, type AiDraftProblem as w, type AiDraftSettings as x, type AiDraftSource as y, type AiDraftType as z };