@intellectif/lk-core 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @intellectif/lk-core
 
+## 0.22.0
+
+### Minor Changes
+
+- [#80](https://github.com/intellectif/learning-kit/pull/80) [`782b01b`](https://github.com/intellectif/learning-kit/commit/782b01ba697a90583b472ab1a7a2be102fd888c4) Thanks [@diego28e](https://github.com/diego28e)! - **Feedback on writing**: "Get feedback on my draft" on a written response in practice. The learner revises and asks again, and every correction must quote what they wrote.
+
+  **Action required:** none unless your code switches exhaustively over `AiFeature` or `AiRefusal` (new members `'writing-feedback'` and `'misquotes-answer'`), reads `AiCheckCase.request` without narrowing on `feature`, or implements a complete `LkStrings` (eight new keys). Nothing changes until you pass a `writingFeedback` port. Otherwise this is a major only because the peer range moves to `@intellectif/lk-core@^0.22.0`.
+
+  - **lk-core:** `aiWritingFeedbackRequest` builds what a model is given: the task, the draft verbatim, its word count as the grader counts it, the rubric, and the feedback on earlier drafts. `checkAiWritingFeedback` checks the reply before a learner sees it. It finds each correction's quote in the draft itself (typographic quotes and runs of whitespace folded, case kept) and anchors it there. A correction of words the draft does not contain refuses the whole reply as `misquotes-answer`. Criteria must be the rubric's; the author's weights are attached, and a model's weight is ignored. The indicative score is `gradeFromRubric`'s total, computed only when every criterion was judged. It is never a grade. Limits: 20 corrections, 500 characters a field.
+  - **lk-react:** a `writingFeedback` port and `maxWritingFeedback` (3 by default, at most 10) on `LearnerAi`. `<WrittenResponse>` shows the feedback with its corrections, rubric comments, the indicative score marked "Not a grade." and the AI notice, and says so once the draft has changed. It is never in `exam` or `review`, and it follows the author's and the paper's `ai.explanations`, `feedback` and `solutions`. `useAiWritingFeedback` gives a written response you draw yourself the same rules.
+  - **Records:** `ai-writing-feedback-shown` (the draft number, how many corrections, the indicative score, provenance and usage; never the text), and `ai-help-refused` with `feature: 'writing-feedback'`.
+  - **ai-check:** a `writingFeedback` port runs four writing cases: a draft with mistakes, one without, a revision, and feedback asked for in Spanish.
+  - Eight new strings: `aiWritingFeedback`, `aiWritingFeedbackLoading`, `aiWritingFeedbackHeading`, `aiWritingFeedbackUnavailable`, `aiNoMoreWritingFeedback`, `aiWritingFeedbackOutdated`, `aiCorrections`, `aiIndicativeScore`.
+
+  Guide: https://github.com/intellectif/learning-kit/blob/main/docs/ai.md#feedback-on-writing
+
 ## 0.21.0
 
 ### Minor Changes

package/README.md

@@ -28,6 +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.
 - **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-xhGV-Aeh.d.cts → activity-CYc7SD3d.d.cts}

@@ -224,7 +224,11 @@ interface GradeRecord {
  * one-word vocabulary item, say.
  */
 interface ActivityAiPermissions {
-    /** An explanation of the learner's graded answer. */
+    /**
+     * 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.
+     */
     explanations?: boolean;
     /** Hints before the learner submits. */
     hints?: boolean;
@@ -243,8 +247,8 @@ interface AiActivityInput {
     readonly redacted?: unknown;
     readonly ai?: unknown;
 }
-/** The two kinds of help a learner can be given. */
-type AiFeature = 'explanation' | 'hint';
+/** The kinds of help a learner can be given. */
+type AiFeature = 'explanation' | 'hint' | 'writing-feedback';
 /** The activity types the SDK builds facts for. */
 type AiSupportedActivityType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation';
 /**
@@ -404,8 +408,117 @@ interface AiTextResult {
      */
     usage?: GraderUsage;
 }
-/** Why a result was not shown. */
-type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer';
+/**
+ * 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.
+ */
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer';
+/** One criterion of a written response's rubric, as the author wrote it. */
+interface AiRubricCriterionFact {
+    name: string;
+    description?: string;
+    weight: number;
+}
+/**
+ * What a model is told about a draft of a written response: the task as the
+ * learner saw it, the draft verbatim, and the rubric it will be graded on.
+ */
+interface AiWritingFacts {
+    activityType: 'written-response';
+    activityId: string;
+    title: string;
+    /** The language the item is written in, when the author gave one. */
+    locale?: string;
+    prompt: string;
+    /** The draft, exactly as the learner wrote it. Every correction quotes it. */
+    text: string;
+    /** Recomputed with `countWords`, as the grader will count it. */
+    wordCount: number;
+    minWords: number;
+    maxWords: number;
+    withinWordBounds: boolean;
+    /** The rubric the answer will be graded on; `null` when the item has none. */
+    rubric: AiRubricCriterionFact[] | null;
+    /** The target language and level, when the author gave one (e.g. `"en-A2"`). */
+    languageTarget?: string;
+}
+/**
+ * Asks for feedback on a draft of a written response, before the learner
+ * submits it. Practice only.
+ */
+interface AiWritingFeedbackRequest {
+    feature: 'writing-feedback';
+    facts: AiWritingFacts;
+    /** 1-based: which draft this is. */
+    draftNumber: number;
+    /** The text of the feedback already shown on earlier drafts, oldest first. */
+    previousFeedback: string[];
+    /** The language to write in: the learner's interface language, when known. */
+    learnerLocale?: string;
+}
+/**
+ * One correction a model proposes. `original` must be words the learner
+ * wrote; the SDK finds them in the draft itself, so a model need not count
+ * characters — leave `range` out unless you are sure of it, because a range
+ * that does not hold the quote is refused.
+ */
+interface AiWritingCorrection {
+    original: string;
+    corrected: string;
+    explanation?: string;
+    /** An error-type tag, e.g. `"tense"`, `"article"`. */
+    category?: string;
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * A model's judgement of one rubric criterion. The SDK attaches the author's
+ * weight; a weight sent here is ignored.
+ */
+type AiCriterionJudgement = Omit<CriterionScore, 'weight'> & {
+    weight?: number;
+};
+/**
+ * What a host's `writingFeedback` port returns: the overall feedback as plain
+ * text, and optionally corrections and a judgement per rubric criterion.
+ */
+interface AiWritingFeedbackResult {
+    /** The overall feedback, addressed to the learner. Plain text, never HTML. */
+    text: string;
+    corrections?: AiWritingCorrection[];
+    criteria?: AiCriterionJudgement[];
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
+/**
+ * Feedback on a draft, as the SDK accepted it: what a learner is shown.
+ */
+interface AiWritingFeedback {
+    text: string;
+    /**
+     * Every correction, anchored in the draft: `range` is where the SDK found
+     * the quote, and `original` is the draft's own text at that range.
+     */
+    corrections: InlineCorrection[];
+    /** The model's judgements, with the rubric's weights. */
+    criteria: CriterionScore[];
+    /**
+     * The rubric's weighted total of the judgements, from 0 to 1, computed by
+     * the SDK as `gradeFromRubric` computes a grade — when every criterion of
+     * the rubric was judged; `null` otherwise, and on an item with no rubric.
+     *
+     * **An indication, never a grade:** it is a model's reading of a draft the
+     * learner has not submitted, and nothing in the SDK scores an answer with
+     * it. `ai-writing-feedback-shown` reports it, so a record can say what the
+     * learner was shown.
+     */
+    indicativeScore: number | null;
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
 
 /**
  * An xAPI Activity object — the thing a statement is about.
@@ -1599,7 +1712,13 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * watches its own model in production, where the development console warning
  * it accompanies is silent.
  */
- | 'ai-help-refused' | (string & {});
+ | 'ai-help-refused'
+/**
+ * Feedback on a draft of a written response was shown (`draftNumber`, the
+ * 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 & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */
@@ -1612,4 +1731,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type MediaPlaybackPolicy as $, type ActivityAiPermissions as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type DictationData as E, type DictationEquivalence as F, type DictationLearnerResponse as G, type DictationSlowMedia as H, type DictationTolerance as I, type FillInTheBlanksData as J, type FillInTheBlanksLearnerResponse as K, type GapSelectBank as L, type GapSelectChoice as M, type GapSelectData as N, type GapSelectGap as O, type GapSelectLearnerResponse as P, type GradeRecord as Q, type Grader as R, type GraderKind as S, type GraderUsage as T, type GradingState as U, type InlineCorrection as V, type InteractionEvent as W, type InteractionKind as X, type ItemOutcome as Y, type LearnerResponse as Z, type LearnerResponseMap as _, type ActivityData as a, type MediaTrack as a0, type MultipleChoiceData as a1, type MultipleChoiceLearnerResponse as a2, type MultipleChoiceOption as a3, type MultipleChoiceOptionMedia as a4, type NativeControlHint as a5, type ReadAloudData as a6, type ReadAloudDimension as a7, type ReadAloudDimensionWeight as a8, type ReadAloudLearnerResponse as a9, type ReadAloudSlowMedia as aa, type RecordingBounds as ab, type RecordingRef as ac, type ScoringDetail as ad, type ScoringOutcome as ae, type ScoringResult as af, type TextMatchPolicy as ag, type TextMatchResult as ah, type ValidationError as ai, type ValidationResult as aj, type WrittenResponseData as ak, type WrittenResponseLearnerResponse as al, type WrittenResponseRubric as am, type WrittenResponseRubricCriterion as an, type XAPIActor as ao, type XAPIConfig as ap, type XAPIContext as aq, type XAPIContextActivities as ar, type XAPIError as as, type XAPIObject as at, type XAPIResult as au, type XAPIScore as av, type XAPIStatement as aw, type XAPIVerbObject as ax, levenshteinDistance as ay, matchText as az, type ActivityDataMap as b, type ActivityFeedback as c, type ActivityMedia as d, type ActivityResult as e, type ActivityType as f, type AiActivityInput as g, type AiBlankFact as h, type AiDictationFacts as i, type AiExplanationRequest as j, type AiFeature as k, type AiFillInTheBlanksFacts as l, type AiGapFact as m, type AiGapSelectFacts as n, type AiGrade as o, type AiHintRequest as p, type AiItemFacts as q, type AiMultipleChoiceFacts as r, type AiOptionFact as s, type AiProvenance as t, type AiRefusal as u, type AiSupportedActivityType as v, type AiTextResult as w, type AiVerdict as x, type AiWordFact as y, type DeferredScoringPartial as z };
+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 };

package/dist/{activity-xhGV-Aeh.d.ts → activity-CYc7SD3d.d.ts}

@@ -224,7 +224,11 @@ interface GradeRecord {
  * one-word vocabulary item, say.
  */
 interface ActivityAiPermissions {
-    /** An explanation of the learner's graded answer. */
+    /**
+     * 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.
+     */
     explanations?: boolean;
     /** Hints before the learner submits. */
     hints?: boolean;
@@ -243,8 +247,8 @@ interface AiActivityInput {
     readonly redacted?: unknown;
     readonly ai?: unknown;
 }
-/** The two kinds of help a learner can be given. */
-type AiFeature = 'explanation' | 'hint';
+/** The kinds of help a learner can be given. */
+type AiFeature = 'explanation' | 'hint' | 'writing-feedback';
 /** The activity types the SDK builds facts for. */
 type AiSupportedActivityType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation';
 /**
@@ -404,8 +408,117 @@ interface AiTextResult {
      */
     usage?: GraderUsage;
 }
-/** Why a result was not shown. */
-type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer';
+/**
+ * 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.
+ */
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer';
+/** One criterion of a written response's rubric, as the author wrote it. */
+interface AiRubricCriterionFact {
+    name: string;
+    description?: string;
+    weight: number;
+}
+/**
+ * What a model is told about a draft of a written response: the task as the
+ * learner saw it, the draft verbatim, and the rubric it will be graded on.
+ */
+interface AiWritingFacts {
+    activityType: 'written-response';
+    activityId: string;
+    title: string;
+    /** The language the item is written in, when the author gave one. */
+    locale?: string;
+    prompt: string;
+    /** The draft, exactly as the learner wrote it. Every correction quotes it. */
+    text: string;
+    /** Recomputed with `countWords`, as the grader will count it. */
+    wordCount: number;
+    minWords: number;
+    maxWords: number;
+    withinWordBounds: boolean;
+    /** The rubric the answer will be graded on; `null` when the item has none. */
+    rubric: AiRubricCriterionFact[] | null;
+    /** The target language and level, when the author gave one (e.g. `"en-A2"`). */
+    languageTarget?: string;
+}
+/**
+ * Asks for feedback on a draft of a written response, before the learner
+ * submits it. Practice only.
+ */
+interface AiWritingFeedbackRequest {
+    feature: 'writing-feedback';
+    facts: AiWritingFacts;
+    /** 1-based: which draft this is. */
+    draftNumber: number;
+    /** The text of the feedback already shown on earlier drafts, oldest first. */
+    previousFeedback: string[];
+    /** The language to write in: the learner's interface language, when known. */
+    learnerLocale?: string;
+}
+/**
+ * One correction a model proposes. `original` must be words the learner
+ * wrote; the SDK finds them in the draft itself, so a model need not count
+ * characters — leave `range` out unless you are sure of it, because a range
+ * that does not hold the quote is refused.
+ */
+interface AiWritingCorrection {
+    original: string;
+    corrected: string;
+    explanation?: string;
+    /** An error-type tag, e.g. `"tense"`, `"article"`. */
+    category?: string;
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * A model's judgement of one rubric criterion. The SDK attaches the author's
+ * weight; a weight sent here is ignored.
+ */
+type AiCriterionJudgement = Omit<CriterionScore, 'weight'> & {
+    weight?: number;
+};
+/**
+ * What a host's `writingFeedback` port returns: the overall feedback as plain
+ * text, and optionally corrections and a judgement per rubric criterion.
+ */
+interface AiWritingFeedbackResult {
+    /** The overall feedback, addressed to the learner. Plain text, never HTML. */
+    text: string;
+    corrections?: AiWritingCorrection[];
+    criteria?: AiCriterionJudgement[];
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
+/**
+ * Feedback on a draft, as the SDK accepted it: what a learner is shown.
+ */
+interface AiWritingFeedback {
+    text: string;
+    /**
+     * Every correction, anchored in the draft: `range` is where the SDK found
+     * the quote, and `original` is the draft's own text at that range.
+     */
+    corrections: InlineCorrection[];
+    /** The model's judgements, with the rubric's weights. */
+    criteria: CriterionScore[];
+    /**
+     * The rubric's weighted total of the judgements, from 0 to 1, computed by
+     * the SDK as `gradeFromRubric` computes a grade — when every criterion of
+     * the rubric was judged; `null` otherwise, and on an item with no rubric.
+     *
+     * **An indication, never a grade:** it is a model's reading of a draft the
+     * learner has not submitted, and nothing in the SDK scores an answer with
+     * it. `ai-writing-feedback-shown` reports it, so a record can say what the
+     * learner was shown.
+     */
+    indicativeScore: number | null;
+    provenance?: AiProvenance;
+    usage?: GraderUsage;
+}
 
 /**
  * An xAPI Activity object — the thing a statement is about.
@@ -1599,7 +1712,13 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * watches its own model in production, where the development console warning
  * it accompanies is silent.
  */
- | 'ai-help-refused' | (string & {});
+ | 'ai-help-refused'
+/**
+ * Feedback on a draft of a written response was shown (`draftNumber`, the
+ * 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 & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */
@@ -1612,4 +1731,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type MediaPlaybackPolicy as $, type ActivityAiPermissions as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type DictationData as E, type DictationEquivalence as F, type DictationLearnerResponse as G, type DictationSlowMedia as H, type DictationTolerance as I, type FillInTheBlanksData as J, type FillInTheBlanksLearnerResponse as K, type GapSelectBank as L, type GapSelectChoice as M, type GapSelectData as N, type GapSelectGap as O, type GapSelectLearnerResponse as P, type GradeRecord as Q, type Grader as R, type GraderKind as S, type GraderUsage as T, type GradingState as U, type InlineCorrection as V, type InteractionEvent as W, type InteractionKind as X, type ItemOutcome as Y, type LearnerResponse as Z, type LearnerResponseMap as _, type ActivityData as a, type MediaTrack as a0, type MultipleChoiceData as a1, type MultipleChoiceLearnerResponse as a2, type MultipleChoiceOption as a3, type MultipleChoiceOptionMedia as a4, type NativeControlHint as a5, type ReadAloudData as a6, type ReadAloudDimension as a7, type ReadAloudDimensionWeight as a8, type ReadAloudLearnerResponse as a9, type ReadAloudSlowMedia as aa, type RecordingBounds as ab, type RecordingRef as ac, type ScoringDetail as ad, type ScoringOutcome as ae, type ScoringResult as af, type TextMatchPolicy as ag, type TextMatchResult as ah, type ValidationError as ai, type ValidationResult as aj, type WrittenResponseData as ak, type WrittenResponseLearnerResponse as al, type WrittenResponseRubric as am, type WrittenResponseRubricCriterion as an, type XAPIActor as ao, type XAPIConfig as ap, type XAPIContext as aq, type XAPIContextActivities as ar, type XAPIError as as, type XAPIObject as at, type XAPIResult as au, type XAPIScore as av, type XAPIStatement as aw, type XAPIVerbObject as ax, levenshteinDistance as ay, matchText as az, type ActivityDataMap as b, type ActivityFeedback as c, type ActivityMedia as d, type ActivityResult as e, type ActivityType as f, type AiActivityInput as g, type AiBlankFact as h, type AiDictationFacts as i, type AiExplanationRequest as j, type AiFeature as k, type AiFillInTheBlanksFacts as l, type AiGapFact as m, type AiGapSelectFacts as n, type AiGrade as o, type AiHintRequest as p, type AiItemFacts as q, type AiMultipleChoiceFacts as r, type AiOptionFact as s, type AiProvenance as t, type AiRefusal as u, type AiSupportedActivityType as v, type AiTextResult as w, type AiVerdict as x, type AiWordFact as y, type DeferredScoringPartial as z };
+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 };

package/dist/ai-check.cjs

@@ -3,7 +3,9 @@
 
 
 
-var _chunkNRTP7WCWcjs = require('./chunk-NRTP7WCW.cjs');
+
+
+var _chunkOPMY2MNScjs = require('./chunk-OPMY2MNS.cjs');
 require('./chunk-WQVZPIN7.cjs');
 require('./chunk-D4TOPSHV.cjs');
 
@@ -68,6 +70,23 @@ var listening = {
   title: "Listen and type",
   transcript: "The train leaves at half past nine."
 };
+var weekend = {
+  schemaVersion: "1.0",
+  type: "written-response",
+  id: "ai-check-writing",
+  title: "Your weekend",
+  prompt: "Write a few sentences about what you did last weekend.",
+  minWords: 15,
+  maxWords: 120,
+  languageTarget: "en-A2",
+  rubric: {
+    criteria: [
+      { name: "Grammar", description: "Past tenses, articles, agreement", weight: 2 },
+      { name: "Vocabulary", description: "Everyday words, used correctly", weight: 1 },
+      { name: "Task", description: "Says what the learner did, in order", weight: 1 }
+    ]
+  }
+};
 var chose = (ids) => ({
   type: "multiple-choice",
   selectedOptionIds: ids
@@ -81,20 +100,37 @@ var picked = (choices) => ({
   selections: choices
 });
 var wrote = (text) => ({ type: "dictation", text });
+var drafted = (text) => ({
+  type: "written-response",
+  text,
+  wordCount: 0
+});
 function explanationCase(id, about, data, response) {
-  const request = _chunkNRTP7WCWcjs.aiExplanationRequest.call(void 0, { data, response });
+  const request = _chunkOPMY2MNScjs.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 = _chunkNRTP7WCWcjs.aiHintRequest.call(void 0, { data, response, previousHints });
+  const request = _chunkOPMY2MNScjs.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 = _chunkOPMY2MNScjs.aiWritingFeedbackRequest.call(void 0, {
+    data: weekend,
+    response: drafted(text),
+    previousFeedback,
+    ...learnerLocale !== void 0 ? { learnerLocale } : {}
+  });
+  if (request === null) {
+    throw new Error(`ai-check: no writing feedback request for "${id}"`);
+  }
+  return { id, feature: "writing-feedback", about, request };
+}
 function aiCheckCases() {
   return [
     explanationCase("mc-correct", "Chose the right city", capital, chose(["madrid"])),
@@ -161,6 +197,29 @@ function aiCheckCases() {
       landscape,
       picked({ g1: "campo" }),
       ["Piensa en la forma del terreno."]
+    ),
+    writingCase(
+      "writing-mistakes",
+      "A first draft with tense, article and agreement mistakes",
+      "Last weekend I go to the market and buyed a apple. My friends was there too, so we don't go home early. Then I go to the cinema."
+    ),
+    writingCase(
+      "writing-clean",
+      "A first draft with no mistakes to correct",
+      "Last weekend I went to the market and bought an apple. My friends were there too, so we stayed until the evening. Then we went to the cinema."
+    ),
+    writingCase(
+      "writing-revised",
+      "A second draft that fixed some mistakes",
+      "Last weekend I went to the market and bought a apple. My friends was there too, so we didn't go home early.",
+      ['Check your past tenses: "go" and "buyed" should be past forms.']
+    ),
+    writingCase(
+      "writing-feedback-in-spanish",
+      "A first draft, with feedback asked for in Spanish",
+      "Last weekend I visit my grandmother. She cook a big lunch and we eat together in the garden.",
+      [],
+      "es"
     )
   ];
 }
@@ -171,13 +230,23 @@ var REFUSALS = [
   "empty",
   "too-long",
   "contradicts-grade",
-  "reveals-answer"
+  "reveals-answer",
+  "misquotes-answer"
 ];
+function portFor(ports, one) {
+  switch (one.request.feature) {
+    case "explanation":
+      return ports.explain;
+    case "hint":
+      return ports.hint;
+    default:
+      return ports.writingFeedback;
+  }
+}
 var now = () => Date.now();
 async function runCase(ports, one) {
   const started = now();
-  const explaining = one.request.feature === "explanation";
-  const port = explaining ? ports.explain : ports.hint;
+  const port = portFor(ports, one);
   if (port === void 0) {
     throw new Error(`ai-check: no port for "${one.id}"`);
   }
@@ -193,15 +262,36 @@ async function runCase(ports, one) {
     };
   }
   const ms = now() - started;
-  const checked = explaining ? _chunkNRTP7WCWcjs.checkAiExplanation.call(void 0, raw, one.request) : _chunkNRTP7WCWcjs.checkAiHint.call(void 0, raw, one.request);
+  if (one.request.feature === "writing-feedback") {
+    const checked2 = _chunkOPMY2MNScjs.checkAiWritingFeedback.call(void 0, raw, one.request);
+    if (checked2.ok) {
+      const { text, provenance, usage } = checked2.feedback;
+      return {
+        case: one,
+        ok: true,
+        result: {
+          text,
+          ...provenance !== void 0 ? { provenance } : {},
+          ...usage !== void 0 ? { usage } : {}
+        },
+        feedback: checked2.feedback,
+        ms
+      };
+    }
+    return refused(one, raw, checked2.refusal, ms);
+  }
+  const checked = one.request.feature === "explanation" ? _chunkOPMY2MNScjs.checkAiExplanation.call(void 0, raw, one.request) : _chunkOPMY2MNScjs.checkAiHint.call(void 0, raw, one.request);
   if (checked.ok) {
     return { case: one, ok: true, result: checked.result, ms };
   }
+  return refused(one, raw, checked.refusal, ms);
+}
+function refused(one, raw, refusal, ms) {
   const text = typeof _optionalChain([raw, 'optionalAccess', _ => _.text]) === "string" ? raw : void 0;
   return {
     case: one,
     ok: false,
-    refusal: checked.refusal,
+    refusal,
     ...text !== void 0 ? { result: text } : {},
     ms
   };
@@ -210,9 +300,7 @@ async function runAiCheck(ports, options = {}) {
   const all = _nullishCoalesce(options.cases, () => ( aiCheckCases()));
   const asked = Math.trunc(_nullishCoalesce(options.concurrency, () => ( 1)));
   const lanes = Number.isFinite(asked) && asked >= 1 ? Math.min(asked, 16) : 1;
-  const runnable = all.filter(
-    (one) => one.request.feature === "explanation" ? ports.explain !== void 0 : ports.hint !== void 0
-  );
+  const runnable = all.filter((one) => portFor(ports, one) !== void 0);
   const results = new Array(runnable.length);
   let next = 0;
   const lane = async () => {
@@ -229,13 +317,13 @@ async function runAiCheck(ports, options = {}) {
   await Promise.all(Array.from({ length: Math.min(lanes, runnable.length) }, lane));
   const byRefusal = Object.fromEntries(REFUSALS.map((reason) => [reason, 0]));
   let shown = 0;
-  let refused = 0;
+  let refused2 = 0;
   let errors = 0;
   for (const result of results) {
     if (result.ok) {
       shown += 1;
     } else if (result.refusal !== void 0) {
-      refused += 1;
+      refused2 += 1;
       byRefusal[result.refusal] += 1;
     } else {
       errors += 1;
@@ -244,7 +332,7 @@ async function runAiCheck(ports, options = {}) {
   return {
     total: results.length,
     shown,
-    refused,
+    refused: refused2,
     errors,
     skipped: all.length - runnable.length,
     byRefusal,