@intellectif/lk-core 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +2 -2
  3. package/dist/ai-CnmLPMzd.d.cts +2417 -0
  4. package/dist/ai-CnmLPMzd.d.cts.map +1 -0
  5. package/dist/ai-CnmLPMzd.d.ts +2417 -0
  6. package/dist/ai-CnmLPMzd.d.ts.map +1 -0
  7. package/dist/ai-check.cjs +845 -620
  8. package/dist/ai-check.cjs.map +1 -1
  9. package/dist/ai-check.d.cts +82 -80
  10. package/dist/ai-check.d.cts.map +1 -0
  11. package/dist/ai-check.d.ts +82 -80
  12. package/dist/ai-check.d.ts.map +1 -0
  13. package/dist/ai-check.js +843 -621
  14. package/dist/ai-check.js.map +1 -1
  15. package/dist/ai-writing-CPpH9Qxq.js +2601 -0
  16. package/dist/ai-writing-CPpH9Qxq.js.map +1 -0
  17. package/dist/ai-writing-G6tnCGzw.cjs +2846 -0
  18. package/dist/ai-writing-G6tnCGzw.cjs.map +1 -0
  19. package/dist/index-2nigSf4N.d.cts +339 -0
  20. package/dist/index-2nigSf4N.d.cts.map +1 -0
  21. package/dist/index-B54baFUA.d.ts +339 -0
  22. package/dist/index-B54baFUA.d.ts.map +1 -0
  23. package/dist/index-BAfEHCnD.d.cts +1071 -0
  24. package/dist/index-BAfEHCnD.d.cts.map +1 -0
  25. package/dist/index-BqMXWuNC.d.cts +153 -0
  26. package/dist/index-BqMXWuNC.d.cts.map +1 -0
  27. package/dist/index-CVWvymVb.d.ts +1071 -0
  28. package/dist/index-CVWvymVb.d.ts.map +1 -0
  29. package/dist/index-CcHDTxIZ.d.ts +153 -0
  30. package/dist/index-CcHDTxIZ.d.ts.map +1 -0
  31. package/dist/index.cjs +1211 -1146
  32. package/dist/index.cjs.map +1 -1
  33. package/dist/index.d.cts +941 -861
  34. package/dist/index.d.cts.map +1 -0
  35. package/dist/index.d.ts +941 -861
  36. package/dist/index.d.ts.map +1 -0
  37. package/dist/index.js +1063 -1147
  38. package/dist/index.js.map +1 -1
  39. package/dist/item-group-DXiR8nOr.js +445 -0
  40. package/dist/item-group-DXiR8nOr.js.map +1 -0
  41. package/dist/item-group-DroFXgLb.cjs +505 -0
  42. package/dist/item-group-DroFXgLb.cjs.map +1 -0
  43. package/dist/registry-DVi0LR_i.cjs +5915 -0
  44. package/dist/registry-DVi0LR_i.cjs.map +1 -0
  45. package/dist/registry-Dsx9mNsS.js +5449 -0
  46. package/dist/registry-Dsx9mNsS.js.map +1 -0
  47. package/dist/schemas-Bdw0nGPo.js +152 -0
  48. package/dist/schemas-Bdw0nGPo.js.map +1 -0
  49. package/dist/schemas-DVbAOrtd.cjs +224 -0
  50. package/dist/schemas-DVbAOrtd.cjs.map +1 -0
  51. package/dist/schemas.cjs +16 -34
  52. package/dist/schemas.d.cts +2 -2
  53. package/dist/schemas.d.ts +2 -2
  54. package/dist/schemas.js +3 -34
  55. package/dist/scoring-B2_HEhMT.cjs +1748 -0
  56. package/dist/scoring-B2_HEhMT.cjs.map +1 -0
  57. package/dist/scoring-BZqUkuDF.js +1604 -0
  58. package/dist/scoring-BZqUkuDF.js.map +1 -0
  59. package/dist/scoring.cjs +37 -75
  60. package/dist/scoring.d.cts +3 -1103
  61. package/dist/scoring.d.ts +3 -1103
  62. package/dist/scoring.js +3 -75
  63. package/dist/xapi-CMTph7wG.js +332 -0
  64. package/dist/xapi-CMTph7wG.js.map +1 -0
  65. package/dist/xapi-DNzkSJ0S.cjs +362 -0
  66. package/dist/xapi-DNzkSJ0S.cjs.map +1 -0
  67. package/dist/xapi.cjs +7 -16
  68. package/dist/xapi.d.cts +2 -150
  69. package/dist/xapi.d.ts +2 -150
  70. package/dist/xapi.js +2 -16
  71. package/package.json +4 -4
  72. package/dist/activity-D705CXng.d.cts +0 -2162
  73. package/dist/activity-D705CXng.d.ts +0 -2162
  74. package/dist/chunk-46BXIGLG.cjs +0 -272
  75. package/dist/chunk-46BXIGLG.cjs.map +0 -1
  76. package/dist/chunk-4YANYTFN.cjs +0 -1256
  77. package/dist/chunk-4YANYTFN.cjs.map +0 -1
  78. package/dist/chunk-7KOWU4RO.js +0 -2207
  79. package/dist/chunk-7KOWU4RO.js.map +0 -1
  80. package/dist/chunk-7THXD7AN.cjs +0 -5057
  81. package/dist/chunk-7THXD7AN.cjs.map +0 -1
  82. package/dist/chunk-CYCTIXUN.cjs +0 -118
  83. package/dist/chunk-CYCTIXUN.cjs.map +0 -1
  84. package/dist/chunk-CYPA5BW5.js +0 -118
  85. package/dist/chunk-CYPA5BW5.js.map +0 -1
  86. package/dist/chunk-JTNDIBZO.js +0 -272
  87. package/dist/chunk-JTNDIBZO.js.map +0 -1
  88. package/dist/chunk-MV2N2WNS.js +0 -352
  89. package/dist/chunk-MV2N2WNS.js.map +0 -1
  90. package/dist/chunk-MXI26H62.cjs +0 -2207
  91. package/dist/chunk-MXI26H62.cjs.map +0 -1
  92. package/dist/chunk-QS7B42ZR.js +0 -5057
  93. package/dist/chunk-QS7B42ZR.js.map +0 -1
  94. package/dist/chunk-QX2ERL72.js +0 -1256
  95. package/dist/chunk-QX2ERL72.js.map +0 -1
  96. package/dist/chunk-ZWXQSKCX.cjs +0 -352
  97. package/dist/chunk-ZWXQSKCX.cjs.map +0 -1
  98. package/dist/index-BChYtrEe.d.ts +0 -548
  99. package/dist/index-VXt_v3YI.d.cts +0 -548
  100. package/dist/schemas.cjs.map +0 -1
  101. package/dist/schemas.js.map +0 -1
  102. package/dist/scoring.cjs.map +0 -1
  103. package/dist/scoring.js.map +0 -1
  104. package/dist/xapi.cjs.map +0 -1
  105. package/dist/xapi.js.map +0 -1
package/dist/ai-check.js CHANGED
@@ -1,662 +1,884 @@
1
- import {
2
- aiCoachingRequest,
3
- aiCritiqueRequest,
4
- aiDraftsRequest,
5
- aiExplanationRequest,
6
- aiHintRequest,
7
- aiWritingFeedbackRequest,
8
- checkAiCoaching,
9
- checkAiCritique,
10
- checkAiDrafts,
11
- checkAiExplanation,
12
- checkAiHint,
13
- checkAiWritingFeedback
14
- } from "./chunk-7KOWU4RO.js";
15
- import {
16
- gradeReadAloud
17
- } from "./chunk-QX2ERL72.js";
18
- import "./chunk-MV2N2WNS.js";
19
- import "./chunk-QS7B42ZR.js";
20
-
21
- // src/ai-check/cases.ts
22
- var capital = {
23
- schemaVersion: "1.0",
24
- type: "multiple-choice",
25
- id: "ai-check-mc",
26
- title: "Capital cities",
27
- question: "What is the capital of Spain?",
28
- mode: "single",
29
- scoringStrategy: "all-or-nothing",
30
- options: [
31
- { id: "madrid", text: "Madrid", isCorrect: true },
32
- { id: "barcelona", text: "Barcelona", isCorrect: false },
33
- { id: "seville", text: "Seville", isCorrect: false }
34
- ]
1
+ import { D as checkAiCoaching, E as aiCoachingRequest, L as checkAiExplanation, M as aiExplanationRequest, P as aiHintRequest, R as checkAiHint, c as aiDraftsRequest, h as checkAiCritique, i as checkAiWritingFeedback, l as checkAiDrafts, m as aiCritiqueRequest, r as aiWritingFeedbackRequest } from "./ai-writing-CPpH9Qxq.js";
2
+ import { o as gradeReadAloud } from "./scoring-BZqUkuDF.js";
3
+ //#region src/ai-check/cases.ts
4
+ /**
5
+ * The items the cases are built from. Small, ordinary language-course content
6
+ * — and deliberately awkward in the places a model slips:
7
+ *
8
+ * - an answer a hint can hardly avoid naming (`Madrid`);
9
+ * - an answer of one short word (`is`), which a hint may write as an ordinary
10
+ * word and must not write beside its neighbour in the passage;
11
+ * - an accented answer (`cañón`), so a hint that spells it without the accent
12
+ * is still caught;
13
+ * - a passage with more than one blank, so a hint can be about the wrong one;
14
+ * - a short essay whose mistakes a model must quote exactly as the learner
15
+ * wrote them — straight apostrophes a model likes to curl, a mistake made
16
+ * twice — so a correction of words nobody wrote is caught;
17
+ * - questions in item groups: a reading passage that prints a question's
18
+ * answer, which a hint must point to without quoting, and a run of blanks
19
+ * whose instructions only the group states.
20
+ */
21
+ const capital = {
22
+ schemaVersion: "1.0",
23
+ type: "multiple-choice",
24
+ id: "ai-check-mc",
25
+ title: "Capital cities",
26
+ question: "What is the capital of Spain?",
27
+ mode: "single",
28
+ scoringStrategy: "all-or-nothing",
29
+ options: [
30
+ {
31
+ id: "madrid",
32
+ text: "Madrid",
33
+ isCorrect: true
34
+ },
35
+ {
36
+ id: "barcelona",
37
+ text: "Barcelona",
38
+ isCorrect: false
39
+ },
40
+ {
41
+ id: "seville",
42
+ text: "Seville",
43
+ isCorrect: false
44
+ }
45
+ ]
46
+ };
47
+ const introduction = {
48
+ schemaVersion: "1.0",
49
+ type: "fill-in-the-blanks",
50
+ id: "ai-check-fib",
51
+ title: "Introducing yourself",
52
+ passage: "My name {{be}} Rossi and I {{live}} in Madrid.",
53
+ blanks: [{
54
+ id: "be",
55
+ acceptedAnswers: ["is"]
56
+ }, {
57
+ id: "live",
58
+ acceptedAnswers: ["live"],
59
+ hint: "Present simple, first person."
60
+ }],
61
+ scoringStrategy: "partial"
62
+ };
63
+ const landscape = {
64
+ schemaVersion: "1.0",
65
+ type: "gap-select",
66
+ id: "ai-check-gap",
67
+ title: "Geography",
68
+ locale: "es-ES",
69
+ passage: "El río pasa por un {{g1}} muy profundo, y el agua {{g2}} fría.",
70
+ gaps: [{
71
+ id: "g1",
72
+ choices: [{
73
+ id: "canon",
74
+ text: "cañón"
75
+ }, {
76
+ id: "campo",
77
+ text: "campo"
78
+ }],
79
+ correctChoiceId: "canon"
80
+ }, {
81
+ id: "g2",
82
+ choices: [{
83
+ id: "esta",
84
+ text: "está"
85
+ }, {
86
+ id: "es",
87
+ text: "es"
88
+ }],
89
+ correctChoiceId: "esta"
90
+ }],
91
+ scoringStrategy: "partial"
92
+ };
93
+ const listening = {
94
+ schemaVersion: "1.0",
95
+ type: "dictation",
96
+ id: "ai-check-dictation",
97
+ title: "Listen and type",
98
+ transcript: "The train leaves at half past nine."
99
+ };
100
+ /**
101
+ * A reading group: a passage, a question it answers word for word, and a
102
+ * summary of it. The question's answer is printed in the passage, so a hint
103
+ * that quotes the passage where it answers is refused.
104
+ */
105
+ const TIDES = "Along most coasts the tide comes in twice a day. It is pulled by the moon: as the Earth turns, the ocean nearest the moon bulges towards it, and so does the ocean on the far side. The highest tides, called spring tides, come when the sun and the moon line up.";
106
+ const springTides = {
107
+ schemaVersion: "1.0",
108
+ type: "multiple-choice",
109
+ id: "ai-check-tides",
110
+ title: "Spring tides",
111
+ question: "When do the highest tides come?",
112
+ mode: "single",
113
+ scoringStrategy: "all-or-nothing",
114
+ options: [
115
+ {
116
+ id: "line-up",
117
+ text: "When the sun and the moon line up",
118
+ isCorrect: true
119
+ },
120
+ {
121
+ id: "full-moon",
122
+ text: "Only at full moon",
123
+ isCorrect: false
124
+ },
125
+ {
126
+ id: "winter",
127
+ text: "In winter",
128
+ isCorrect: false
129
+ }
130
+ ]
35
131
  };
36
- var introduction = {
37
- schemaVersion: "1.0",
38
- type: "fill-in-the-blanks",
39
- id: "ai-check-fib",
40
- title: "Introducing yourself",
41
- passage: "My name {{be}} Rossi and I {{live}} in Madrid.",
42
- blanks: [
43
- { id: "be", acceptedAnswers: ["is"] },
44
- { id: "live", acceptedAnswers: ["live"], hint: "Present simple, first person." }
45
- ],
46
- scoringStrategy: "partial"
132
+ const tidesSummary = {
133
+ schemaVersion: "1.0",
134
+ type: "written-response",
135
+ id: "ai-check-tides-summary",
136
+ title: "Summary",
137
+ prompt: "Summarise the text in one or two sentences.",
138
+ minWords: 10,
139
+ maxWords: 60,
140
+ languageTarget: "en-B1"
47
141
  };
48
- var landscape = {
49
- schemaVersion: "1.0",
50
- type: "gap-select",
51
- id: "ai-check-gap",
52
- title: "Geography",
53
- locale: "es-ES",
54
- passage: "El r\xEDo pasa por un {{g1}} muy profundo, y el agua {{g2}} fr\xEDa.",
55
- gaps: [
56
- {
57
- id: "g1",
58
- choices: [
59
- { id: "canon", text: "ca\xF1\xF3n" },
60
- { id: "campo", text: "campo" }
61
- ],
62
- correctChoiceId: "canon"
63
- },
64
- {
65
- id: "g2",
66
- choices: [
67
- { id: "esta", text: "est\xE1" },
68
- { id: "es", text: "es" }
69
- ],
70
- correctChoiceId: "esta"
71
- }
72
- ],
73
- scoringStrategy: "partial"
142
+ const tides = {
143
+ schemaVersion: "1.0",
144
+ type: "item-group",
145
+ id: "ai-check-tides-group",
146
+ title: "Part 2 — Reading",
147
+ stimulus: {
148
+ id: "ai-check-tides-text",
149
+ kind: "text",
150
+ title: "Tides",
151
+ body: TIDES
152
+ },
153
+ items: [springTides, tidesSummary]
74
154
  };
75
- var listening = {
76
- schemaVersion: "1.0",
77
- type: "dictation",
78
- id: "ai-check-dictation",
79
- title: "Listen and type",
80
- transcript: "The train leaves at half past nine."
155
+ /** A part whose questions share instructions the questions themselves never state. */
156
+ const formation = {
157
+ schemaVersion: "1.0",
158
+ type: "fill-in-the-blanks",
159
+ id: "ai-check-formation",
160
+ title: "Word formation",
161
+ passage: "She smiled {{a}} when she heard the news. (HAPPY)",
162
+ blanks: [{
163
+ id: "a",
164
+ acceptedAnswers: ["happily"]
165
+ }],
166
+ scoringStrategy: "all-or-nothing"
81
167
  };
82
- var weekend = {
83
- schemaVersion: "1.0",
84
- type: "written-response",
85
- id: "ai-check-writing",
86
- title: "Your weekend",
87
- prompt: "Write a few sentences about what you did last weekend.",
88
- minWords: 15,
89
- maxWords: 120,
90
- languageTarget: "en-A2",
91
- rubric: {
92
- criteria: [
93
- { name: "Grammar", description: "Past tenses, articles, agreement", weight: 2 },
94
- { name: "Vocabulary", description: "Everyday words, used correctly", weight: 1 },
95
- { name: "Task", description: "Says what the learner did, in order", weight: 1 }
96
- ]
97
- }
168
+ const formationPart = {
169
+ schemaVersion: "1.0",
170
+ type: "item-group",
171
+ id: "ai-check-formation-part",
172
+ title: "Part 1 — Word formation",
173
+ stimulus: {
174
+ id: "ai-check-formation-instructions",
175
+ kind: "text",
176
+ body: "Use the word in capitals at the end of each sentence to form a word that fits the gap."
177
+ },
178
+ items: [formation]
98
179
  };
99
- var weather = {
100
- schemaVersion: "1.0",
101
- type: "read-aloud",
102
- id: "ai-check-reading",
103
- title: "Read the forecast aloud",
104
- referenceText: "The weather is warm in the north.",
105
- locale: "en-US",
106
- recording: { maxSeconds: 20 },
107
- scoring: {
108
- dimensions: [
109
- { name: "accuracy", weight: 2 },
110
- { name: "fluency", weight: 1 }
111
- ]
112
- }
180
+ const weekend = {
181
+ schemaVersion: "1.0",
182
+ type: "written-response",
183
+ id: "ai-check-writing",
184
+ title: "Your weekend",
185
+ prompt: "Write a few sentences about what you did last weekend.",
186
+ minWords: 15,
187
+ maxWords: 120,
188
+ languageTarget: "en-A2",
189
+ rubric: { criteria: [
190
+ {
191
+ name: "Grammar",
192
+ description: "Past tenses, articles, agreement",
193
+ weight: 2
194
+ },
195
+ {
196
+ name: "Vocabulary",
197
+ description: "Everyday words, used correctly",
198
+ weight: 1
199
+ },
200
+ {
201
+ name: "Task",
202
+ description: "Says what the learner did, in order",
203
+ weight: 1
204
+ }
205
+ ] }
113
206
  };
114
- var said = (text, over = {}) => ({
115
- text,
116
- error: "none",
117
- accuracy: 92,
118
- ...over
207
+ const weather = {
208
+ schemaVersion: "1.0",
209
+ type: "read-aloud",
210
+ id: "ai-check-reading",
211
+ title: "Read the forecast aloud",
212
+ referenceText: "The weather is warm in the north.",
213
+ locale: "en-US",
214
+ recording: { maxSeconds: 20 },
215
+ scoring: { dimensions: [{
216
+ name: "accuracy",
217
+ weight: 2
218
+ }, {
219
+ name: "fluency",
220
+ weight: 1
221
+ }] }
222
+ };
223
+ /** A word of the forecast as an engine reports it. */
224
+ const said = (text, over = {}) => ({
225
+ text,
226
+ error: "none",
227
+ accuracy: 92,
228
+ ...over
119
229
  });
230
+ /**
231
+ * An engine's assessment of the forecast. With `slips`, "weather" is
232
+ * mispronounced — its "th" heard as /d/ or /z/ — and "north" is left out: the
233
+ * marks a model must coach, and no others.
234
+ */
120
235
  function forecast(slips) {
121
- return {
122
- assessmentVersion: "1.0",
123
- status: "assessed",
124
- task: "scripted",
125
- locale: "en-US",
126
- referenceText: weather.referenceText,
127
- recordingKey: "ai-check-take",
128
- assessor: { kind: "auto", id: "pronunciation-engine" },
129
- scale: 100,
130
- scores: slips ? { accuracy: 68, fluency: 81, completeness: 86 } : { accuracy: 94, fluency: 90 },
131
- miscue: "assessor",
132
- phonemeAlphabet: "ipa",
133
- words: [
134
- said("The"),
135
- slips ? said("weather", {
136
- accuracy: 38,
137
- error: "mispronunciation",
138
- phonemes: [
139
- { symbol: "w", accuracy: 90 },
140
- { symbol: "\u025B", accuracy: 85 },
141
- {
142
- symbol: "\xF0",
143
- accuracy: 12,
144
- heardAs: [
145
- { symbol: "d", score: 64 },
146
- { symbol: "z", score: 21 },
147
- { symbol: "\xF0", score: 12 }
148
- ]
149
- },
150
- { symbol: "\u025A", accuracy: 80 }
151
- ]
152
- }) : said("weather"),
153
- said("is"),
154
- said("warm"),
155
- said("in"),
156
- said("the"),
157
- slips ? { text: "north", error: "omission" } : said("north")
158
- ]
159
- };
236
+ return {
237
+ assessmentVersion: "1.0",
238
+ status: "assessed",
239
+ task: "scripted",
240
+ locale: "en-US",
241
+ referenceText: weather.referenceText,
242
+ recordingKey: "ai-check-take",
243
+ assessor: {
244
+ kind: "auto",
245
+ id: "pronunciation-engine"
246
+ },
247
+ scale: 100,
248
+ scores: slips ? {
249
+ accuracy: 68,
250
+ fluency: 81,
251
+ completeness: 86
252
+ } : {
253
+ accuracy: 94,
254
+ fluency: 90
255
+ },
256
+ miscue: "assessor",
257
+ phonemeAlphabet: "ipa",
258
+ words: [
259
+ said("The"),
260
+ slips ? said("weather", {
261
+ accuracy: 38,
262
+ error: "mispronunciation",
263
+ phonemes: [
264
+ {
265
+ symbol: "w",
266
+ accuracy: 90
267
+ },
268
+ {
269
+ symbol: "ɛ",
270
+ accuracy: 85
271
+ },
272
+ {
273
+ symbol: "ð",
274
+ accuracy: 12,
275
+ heardAs: [
276
+ {
277
+ symbol: "d",
278
+ score: 64
279
+ },
280
+ {
281
+ symbol: "z",
282
+ score: 21
283
+ },
284
+ {
285
+ symbol: "ð",
286
+ score: 12
287
+ }
288
+ ]
289
+ },
290
+ {
291
+ symbol: "ɚ",
292
+ accuracy: 80
293
+ }
294
+ ]
295
+ }) : said("weather"),
296
+ said("is"),
297
+ said("warm"),
298
+ said("in"),
299
+ said("the"),
300
+ slips ? {
301
+ text: "north",
302
+ error: "omission"
303
+ } : said("north")
304
+ ]
305
+ };
160
306
  }
161
- var chose = (ids) => ({
162
- type: "multiple-choice",
163
- selectedOptionIds: ids
307
+ const chose = (ids) => ({
308
+ type: "multiple-choice",
309
+ selectedOptionIds: ids
310
+ });
311
+ const typed = (answers) => ({
312
+ type: "fill-in-the-blanks",
313
+ answers
164
314
  });
165
- var typed = (answers) => ({
166
- type: "fill-in-the-blanks",
167
- answers
315
+ const picked = (choices) => ({
316
+ type: "gap-select",
317
+ selections: choices
168
318
  });
169
- var picked = (choices) => ({
170
- type: "gap-select",
171
- selections: choices
319
+ const wrote = (text) => ({
320
+ type: "dictation",
321
+ text
172
322
  });
173
- var wrote = (text) => ({ type: "dictation", text });
174
- var drafted = (text) => ({
175
- type: "written-response",
176
- text,
177
- wordCount: 0
323
+ const drafted = (text) => ({
324
+ type: "written-response",
325
+ text,
326
+ wordCount: 0
178
327
  });
179
- var fruit = {
180
- schemaVersion: "1.0",
181
- type: "multiple-choice",
182
- id: "ai-check-fruit",
183
- title: "Food words",
184
- question: "Which of these is a fruit?",
185
- mode: "single",
186
- scoringStrategy: "all-or-nothing",
187
- options: [
188
- { id: "f1", text: "Apple", isCorrect: true },
189
- { id: "f2", text: "Carrot", isCorrect: false },
190
- { id: "f3", text: "Tomato", isCorrect: false }
191
- ]
328
+ /**
329
+ * Items an author asks a model to review. Each is valid, and each but the last
330
+ * has a flaw a rule cannot see: a distractor that is botanically a right
331
+ * answer, and a task far above the level it is set for.
332
+ */
333
+ const fruit = {
334
+ schemaVersion: "1.0",
335
+ type: "multiple-choice",
336
+ id: "ai-check-fruit",
337
+ title: "Food words",
338
+ question: "Which of these is a fruit?",
339
+ mode: "single",
340
+ scoringStrategy: "all-or-nothing",
341
+ options: [
342
+ {
343
+ id: "f1",
344
+ text: "Apple",
345
+ isCorrect: true
346
+ },
347
+ {
348
+ id: "f2",
349
+ text: "Carrot",
350
+ isCorrect: false
351
+ },
352
+ {
353
+ id: "f3",
354
+ text: "Tomato",
355
+ isCorrect: false
356
+ }
357
+ ]
192
358
  };
193
- var tooHard = {
194
- schemaVersion: "1.0",
195
- type: "written-response",
196
- id: "ai-check-too-hard",
197
- title: "Cities",
198
- prompt: "Discuss the socioeconomic ramifications of rapid urbanisation in developing economies.",
199
- minWords: 40,
200
- maxWords: 80
359
+ const tooHard = {
360
+ schemaVersion: "1.0",
361
+ type: "written-response",
362
+ id: "ai-check-too-hard",
363
+ title: "Cities",
364
+ prompt: "Discuss the socioeconomic ramifications of rapid urbanisation in developing economies.",
365
+ minWords: 40,
366
+ maxWords: 80
201
367
  };
202
- var cleanCloze = {
203
- schemaVersion: "1.0",
204
- type: "fill-in-the-blanks",
205
- id: "ai-check-clean-cloze",
206
- title: "Daily routine",
207
- passage: "Every morning I {{1}} up at seven and {{2}} a shower.",
208
- blanks: [
209
- { id: "1", acceptedAnswers: ["get", "wake"] },
210
- { id: "2", acceptedAnswers: ["take", "have"] }
211
- ],
212
- scoringStrategy: "partial"
368
+ const cleanCloze = {
369
+ schemaVersion: "1.0",
370
+ type: "fill-in-the-blanks",
371
+ id: "ai-check-clean-cloze",
372
+ title: "Daily routine",
373
+ passage: "Every morning I {{1}} up at seven and {{2}} a shower.",
374
+ blanks: [{
375
+ id: "1",
376
+ acceptedAnswers: ["get", "wake"]
377
+ }, {
378
+ id: "2",
379
+ acceptedAnswers: ["take", "have"]
380
+ }],
381
+ scoringStrategy: "partial"
213
382
  };
214
383
  function critiqueCase(id, about, type, draft, extra = {}) {
215
- const request = aiCritiqueRequest({ type, draft, ...extra });
216
- if (request === null) {
217
- throw new Error(`ai-check: no critique request for "${id}"`);
218
- }
219
- return { id, feature: "item-critique", about, request };
384
+ const request = aiCritiqueRequest({
385
+ type,
386
+ draft,
387
+ ...extra
388
+ });
389
+ if (request === null) throw new Error(`ai-check: no critique request for "${id}"`);
390
+ return {
391
+ id,
392
+ feature: "item-critique",
393
+ about,
394
+ request
395
+ };
220
396
  }
221
- var MARKET = "Maria lives in Seville, in the south of Spain. Every Saturday she walks to the market with her grandmother. They buy oranges, fresh bread and a little cheese. On the way home they stop at a caf\xE9, where Maria drinks hot chocolate and her grandmother reads the newspaper.";
222
- var MARKET_CAPTIONS = [
223
- { start: 0, end: 4.2, text: "Maria lives in Seville, in the south of Spain." },
224
- { start: 4.2, end: 8.9, text: "Every Saturday she walks to the market with her grandmother." },
225
- { start: 8.9, end: 12.6, text: "They buy oranges, fresh bread and a little cheese." },
226
- { start: 12.6, end: 18.1, text: "On the way home they stop at a caf\xE9." }
397
+ /** A short reading to draft from: plain, and with facts a question can be asked about. */
398
+ const MARKET = "Maria lives in Seville, in the south of Spain. Every Saturday she walks to the market with her grandmother. They buy oranges, fresh bread and a little cheese. On the way home they stop at a café, where Maria drinks hot chocolate and her grandmother reads the newspaper.";
399
+ /** The same reading as a video's captions, with times in seconds. */
400
+ const MARKET_CAPTIONS = [
401
+ {
402
+ start: 0,
403
+ end: 4.2,
404
+ text: "Maria lives in Seville, in the south of Spain."
405
+ },
406
+ {
407
+ start: 4.2,
408
+ end: 8.9,
409
+ text: "Every Saturday she walks to the market with her grandmother."
410
+ },
411
+ {
412
+ start: 8.9,
413
+ end: 12.6,
414
+ text: "They buy oranges, fresh bread and a little cheese."
415
+ },
416
+ {
417
+ start: 12.6,
418
+ end: 18.1,
419
+ text: "On the way home they stop at a café."
420
+ }
227
421
  ];
228
422
  function draftsCase(id, about, types, source, extra = {}) {
229
- const request = aiDraftsRequest({ types, source, ...extra });
230
- if (request === null) {
231
- throw new Error(`ai-check: no drafts request for "${id}"`);
232
- }
233
- return { id, feature: "draft-generation", about, request };
423
+ const request = aiDraftsRequest({
424
+ types,
425
+ source,
426
+ ...extra
427
+ });
428
+ if (request === null) throw new Error(`ai-check: no drafts request for "${id}"`);
429
+ return {
430
+ id,
431
+ feature: "draft-generation",
432
+ about,
433
+ request
434
+ };
234
435
  }
235
- var READ_ALOUD_SETTINGS = {
236
- locale: "en-US",
237
- recording: { maxSeconds: 20 },
238
- scoring: { dimensions: [{ name: "accuracy", weight: 1 }] }
436
+ /**
437
+ * What a host sets on every read-aloud it drafts: the SDK has no default for a
438
+ * recording's length or the dimensions a reading is graded on.
439
+ */
440
+ const READ_ALOUD_SETTINGS = {
441
+ locale: "en-US",
442
+ recording: { maxSeconds: 20 },
443
+ scoring: { dimensions: [{
444
+ name: "accuracy",
445
+ weight: 1
446
+ }] }
239
447
  };
240
- function explanationCase(id, about, data, response) {
241
- const request = aiExplanationRequest({ data, response });
242
- if (request === null) {
243
- throw new Error(`ai-check: no explanation request for "${id}"`);
244
- }
245
- return { id, feature: "explanation", about, request };
448
+ /** Builds a case, failing loudly rather than shipping a case with no request. */
449
+ function explanationCase(id, about, data, response, group) {
450
+ const request = aiExplanationRequest({
451
+ data,
452
+ response,
453
+ ...group ? { group } : {}
454
+ });
455
+ if (request === null) throw new Error(`ai-check: no explanation request for "${id}"`);
456
+ return {
457
+ id,
458
+ feature: "explanation",
459
+ about,
460
+ request
461
+ };
246
462
  }
247
- function hintCase(id, about, data, response, previousHints = []) {
248
- const request = aiHintRequest({ data, response, previousHints });
249
- if (request === null) {
250
- throw new Error(`ai-check: no hint request for "${id}"`);
251
- }
252
- return { id, feature: "hint", about, request };
463
+ function hintCase(id, about, data, response, previousHints = [], group) {
464
+ const request = aiHintRequest({
465
+ data,
466
+ response,
467
+ previousHints,
468
+ ...group ? { group } : {}
469
+ });
470
+ if (request === null) throw new Error(`ai-check: no hint request for "${id}"`);
471
+ return {
472
+ id,
473
+ feature: "hint",
474
+ about,
475
+ request
476
+ };
253
477
  }
254
- function writingCase(id, about, text, previousFeedback = [], learnerLocale) {
255
- const request = aiWritingFeedbackRequest({
256
- data: weekend,
257
- response: drafted(text),
258
- previousFeedback,
259
- ...learnerLocale !== void 0 ? { learnerLocale } : {}
260
- });
261
- if (request === null) {
262
- throw new Error(`ai-check: no writing feedback request for "${id}"`);
263
- }
264
- return { id, feature: "writing-feedback", about, request };
478
+ function writingCase(id, about, text, previousFeedback = [], learnerLocale, task = { data: weekend }) {
479
+ const request = aiWritingFeedbackRequest({
480
+ data: task.data,
481
+ response: drafted(text),
482
+ previousFeedback,
483
+ ...task.group ? { group: task.group } : {},
484
+ ...learnerLocale !== void 0 ? { learnerLocale } : {}
485
+ });
486
+ if (request === null) throw new Error(`ai-check: no writing feedback request for "${id}"`);
487
+ return {
488
+ id,
489
+ feature: "writing-feedback",
490
+ about,
491
+ request
492
+ };
265
493
  }
266
494
  function coachingCase(id, about, marks, learnerLocale) {
267
- const assessment = marks.assessment ?? forecast(true);
268
- const grade = gradeReadAloud(
269
- weather,
270
- { type: "read-aloud", recording: { key: "ai-check-take", mimeType: "audio/wav" } },
271
- assessment,
272
- {
273
- measured: { durationMs: 4e3, voicedMs: 3e3 },
274
- plausibility: { maxWordsPerSecond: 6, minVoicedMs: 500 }
275
- }
276
- );
277
- if ("unscorable" in grade) {
278
- throw new Error(`ai-check: the reading for "${id}" did not grade: ${grade.reason}`);
279
- }
280
- const request = aiCoachingRequest({
281
- data: weather,
282
- ...marks.fromGradeOnly === true ? {} : { assessment },
283
- grade,
284
- ...learnerLocale !== void 0 ? { learnerLocale } : {}
285
- });
286
- if (request === null) {
287
- throw new Error(`ai-check: no coaching request for "${id}"`);
288
- }
289
- return { id, feature: "pronunciation-coaching", about, request };
495
+ const assessment = marks.assessment ?? forecast(true);
496
+ const grade = gradeReadAloud(weather, {
497
+ type: "read-aloud",
498
+ recording: {
499
+ key: "ai-check-take",
500
+ mimeType: "audio/wav"
501
+ }
502
+ }, assessment, {
503
+ measured: {
504
+ durationMs: 4e3,
505
+ voicedMs: 3e3
506
+ },
507
+ plausibility: {
508
+ maxWordsPerSecond: 6,
509
+ minVoicedMs: 500
510
+ }
511
+ });
512
+ if ("unscorable" in grade) throw new Error(`ai-check: the reading for "${id}" did not grade: ${grade.reason}`);
513
+ const request = aiCoachingRequest({
514
+ data: weather,
515
+ ...marks.fromGradeOnly === true ? {} : { assessment },
516
+ grade,
517
+ ...learnerLocale !== void 0 ? { learnerLocale } : {}
518
+ });
519
+ if (request === null) throw new Error(`ai-check: no coaching request for "${id}"`);
520
+ return {
521
+ id,
522
+ feature: "pronunciation-coaching",
523
+ about,
524
+ request
525
+ };
290
526
  }
527
+ /**
528
+ * The cases {@link runAiCheck} runs: every type the SDK explains, answered
529
+ * right, wrong and — where a type can be — partly right; every type it hints
530
+ * for, before an answer and after a wrong one; and drafts of an essay, with
531
+ * mistakes, without, and revised.
532
+ *
533
+ * They are ordinary calls. What makes them a test is that the SDK knows the
534
+ * answer to each, so it can check what your model writes about it.
535
+ *
536
+ * A fresh array each call, so a caller may filter, slice or add to it without
537
+ * changing what the next caller gets.
538
+ */
291
539
  function aiCheckCases() {
292
- return [
293
- explanationCase("mc-correct", "Chose the right city", capital, chose(["madrid"])),
294
- explanationCase("mc-wrong", "Chose Barcelona", capital, chose(["barcelona"])),
295
- explanationCase("mc-blank", "Chose nothing and submitted", capital, chose([])),
296
- explanationCase(
297
- "fib-correct",
298
- "Filled both blanks correctly",
299
- introduction,
300
- typed({ be: "is", live: "live" })
301
- ),
302
- explanationCase(
303
- "fib-partly",
304
- "One blank right, one wrong",
305
- introduction,
306
- typed({ be: "is", live: "lives" })
307
- ),
308
- explanationCase(
309
- "fib-wrong",
310
- "Both blanks wrong",
311
- introduction,
312
- typed({ be: "are", live: "living" })
313
- ),
314
- explanationCase(
315
- "gap-partly",
316
- "One gap right, one wrong, in Spanish",
317
- landscape,
318
- picked({ g1: "canon", g2: "es" })
319
- ),
320
- explanationCase(
321
- "gap-wrong",
322
- "Both gaps wrong, in Spanish",
323
- landscape,
324
- picked({ g1: "campo", g2: "es" })
325
- ),
326
- explanationCase(
327
- "dictation-near",
328
- "Typed the sentence with two words wrong",
329
- listening,
330
- wrote("The train leaves at half past five")
331
- ),
332
- explanationCase(
333
- "dictation-correct",
334
- "Typed the sentence correctly",
335
- listening,
336
- wrote("The train leaves at half past nine.")
337
- ),
338
- hintCase("mc-hint-1", "Has not answered yet", capital, chose([])),
339
- hintCase("mc-hint-2", "Asked again after choosing Seville", capital, chose(["seville"]), [
340
- "Think about where the government sits."
341
- ]),
342
- hintCase("fib-hint-1", "Both blanks empty", introduction, typed({})),
343
- hintCase(
344
- "fib-hint-2",
345
- "Asked again with one blank wrong",
346
- introduction,
347
- typed({ be: "are", live: "" }),
348
- ["Look again at the first blank."]
349
- ),
350
- hintCase("gap-hint-1", "Neither gap chosen, in Spanish", landscape, picked({})),
351
- hintCase(
352
- "gap-hint-2",
353
- "Asked again with the first gap wrong",
354
- landscape,
355
- picked({ g1: "campo" }),
356
- ["Piensa en la forma del terreno."]
357
- ),
358
- writingCase(
359
- "writing-mistakes",
360
- "A first draft with tense, article and agreement mistakes",
361
- "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."
362
- ),
363
- writingCase(
364
- "writing-clean",
365
- "A first draft with no mistakes to correct",
366
- "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."
367
- ),
368
- writingCase(
369
- "writing-revised",
370
- "A second draft that fixed some mistakes",
371
- "Last weekend I went to the market and bought a apple. My friends was there too, so we didn't go home early.",
372
- ['Check your past tenses: "go" and "buyed" should be past forms.']
373
- ),
374
- writingCase(
375
- "writing-feedback-in-spanish",
376
- "A first draft, with feedback asked for in Spanish",
377
- "Last weekend I visit my grandmother. She cook a big lunch and we eat together in the garden.",
378
- [],
379
- "es"
380
- ),
381
- coachingCase("coaching-slips", 'A reading with a mispronounced "th" and a word left out', {
382
- assessment: forecast(true)
383
- }),
384
- coachingCase("coaching-clean", "A reading the engine marked correct throughout", {
385
- assessment: forecast(false)
386
- }),
387
- coachingCase(
388
- "coaching-from-grade",
389
- "The same slips, from a stored grade: marks without sounds",
390
- { fromGradeOnly: true }
391
- ),
392
- coachingCase(
393
- "coaching-in-spanish",
394
- "The same slips, with coaching asked for in Spanish",
395
- { assessment: forecast(true) },
396
- "es"
397
- ),
398
- critiqueCase(
399
- "critique-second-answer",
400
- 'A question whose distractor "Tomato" is botanically a fruit',
401
- "multiple-choice",
402
- fruit,
403
- { level: "A1" }
404
- ),
405
- critiqueCase(
406
- "critique-level",
407
- "A writing task far above the A1 level it is set for",
408
- "written-response",
409
- tooHard,
410
- { level: "A1" }
411
- ),
412
- critiqueCase(
413
- "critique-clean",
414
- "A cloze with nothing wrong in it",
415
- "fill-in-the-blanks",
416
- cleanCloze,
417
- {
418
- level: "A2"
419
- }
420
- ),
421
- critiqueCase(
422
- "critique-in-spanish",
423
- "The fruit question, reviewed in Spanish for its author",
424
- "multiple-choice",
425
- fruit,
426
- { level: "A1", authorLocale: "es" }
427
- ),
428
- draftsCase(
429
- "drafts-questions",
430
- "Four multiple-choice questions on a short reading",
431
- ["multiple-choice"],
432
- { kind: "passage", text: MARKET },
433
- { count: 4, level: "A2", locale: "en" }
434
- ),
435
- draftsCase(
436
- "drafts-cloze",
437
- "A cloze on the same reading, from its transcript",
438
- ["fill-in-the-blanks"],
439
- { kind: "transcript", text: MARKET },
440
- { count: 1, level: "A2", locale: "en", instructions: "Blank the verbs." }
441
- ),
442
- draftsCase(
443
- "drafts-gaps",
444
- "A choose-the-word item on the same reading",
445
- ["gap-select"],
446
- { kind: "passage", text: MARKET },
447
- { count: 1, level: "A2", locale: "en" }
448
- ),
449
- draftsCase(
450
- "drafts-writing",
451
- "A writing task that follows on from the reading",
452
- ["written-response"],
453
- { kind: "passage", text: MARKET },
454
- { count: 1, level: "A2", locale: "en" }
455
- ),
456
- draftsCase(
457
- "drafts-video",
458
- "A video quiz from timed captions: multiple choice, then dictation, then read-aloud, as many as the video is worth",
459
- ["multiple-choice", "dictation", "read-aloud"],
460
- { kind: "captions", cues: MARKET_CAPTIONS },
461
- { level: "A2", locale: "en", settings: { "read-aloud": READ_ALOUD_SETTINGS } }
462
- ),
463
- draftsCase(
464
- "drafts-script",
465
- "The same video from its script alone, with no times, and what the author asked for",
466
- ["multiple-choice", "dictation", "read-aloud"],
467
- { kind: "transcript", text: MARKET },
468
- {
469
- level: "A2",
470
- locale: "en",
471
- instructions: "Focus on what Maria and her grandmother buy.",
472
- settings: { "read-aloud": READ_ALOUD_SETTINGS }
473
- }
474
- )
475
- ];
540
+ return [
541
+ explanationCase("mc-correct", "Chose the right city", capital, chose(["madrid"])),
542
+ explanationCase("mc-wrong", "Chose Barcelona", capital, chose(["barcelona"])),
543
+ explanationCase("mc-blank", "Chose nothing and submitted", capital, chose([])),
544
+ explanationCase("fib-correct", "Filled both blanks correctly", introduction, typed({
545
+ be: "is",
546
+ live: "live"
547
+ })),
548
+ explanationCase("fib-partly", "One blank right, one wrong", introduction, typed({
549
+ be: "is",
550
+ live: "lives"
551
+ })),
552
+ explanationCase("fib-wrong", "Both blanks wrong", introduction, typed({
553
+ be: "are",
554
+ live: "living"
555
+ })),
556
+ explanationCase("gap-partly", "One gap right, one wrong, in Spanish", landscape, picked({
557
+ g1: "canon",
558
+ g2: "es"
559
+ })),
560
+ explanationCase("gap-wrong", "Both gaps wrong, in Spanish", landscape, picked({
561
+ g1: "campo",
562
+ g2: "es"
563
+ })),
564
+ explanationCase("dictation-near", "Typed the sentence with two words wrong", listening, wrote("The train leaves at half past five")),
565
+ explanationCase("dictation-correct", "Typed the sentence correctly", listening, wrote("The train leaves at half past nine.")),
566
+ explanationCase("mc-reading-wrong", "Chose 'Only at full moon', on a question about its group's passage", springTides, chose(["full-moon"]), tides),
567
+ hintCase("mc-hint-1", "Has not answered yet", capital, chose([])),
568
+ hintCase("mc-hint-2", "Asked again after choosing Seville", capital, chose(["seville"]), ["Think about where the government sits."]),
569
+ hintCase("fib-hint-1", "Both blanks empty", introduction, typed({})),
570
+ hintCase("fib-hint-2", "Asked again with one blank wrong", introduction, typed({
571
+ be: "are",
572
+ live: ""
573
+ }), ["Look again at the first blank."]),
574
+ hintCase("gap-hint-1", "Neither gap chosen, in Spanish", landscape, picked({})),
575
+ hintCase("gap-hint-2", "Asked again with the first gap wrong", landscape, picked({ g1: "campo" }), ["Piensa en la forma del terreno."]),
576
+ hintCase("mc-reading-hint", "Has not answered a question whose answer its group's passage prints", springTides, chose([]), [], tides),
577
+ hintCase("fib-formation-hint", "A word-formation blank, under the instructions its group gives", formation, typed({}), [], formationPart),
578
+ 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."),
579
+ 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."),
580
+ 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."]),
581
+ 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"),
582
+ writingCase("writing-summary", "A summary of its group's passage that gets the spring tides wrong", "The tide comes in twice a day because the moon pulls the ocean. The highest tides come only at full moon.", [], void 0, {
583
+ data: tidesSummary,
584
+ group: tides
585
+ }),
586
+ coachingCase("coaching-slips", "A reading with a mispronounced \"th\" and a word left out", { assessment: forecast(true) }),
587
+ coachingCase("coaching-clean", "A reading the engine marked correct throughout", { assessment: forecast(false) }),
588
+ coachingCase("coaching-from-grade", "The same slips, from a stored grade: marks without sounds", { fromGradeOnly: true }),
589
+ coachingCase("coaching-in-spanish", "The same slips, with coaching asked for in Spanish", { assessment: forecast(true) }, "es"),
590
+ critiqueCase("critique-second-answer", "A question whose distractor \"Tomato\" is botanically a fruit", "multiple-choice", fruit, { level: "A1" }),
591
+ critiqueCase("critique-level", "A writing task far above the A1 level it is set for", "written-response", tooHard, { level: "A1" }),
592
+ critiqueCase("critique-clean", "A cloze with nothing wrong in it", "fill-in-the-blanks", cleanCloze, { level: "A2" }),
593
+ critiqueCase("critique-in-spanish", "The fruit question, reviewed in Spanish for its author", "multiple-choice", fruit, {
594
+ level: "A1",
595
+ authorLocale: "es"
596
+ }),
597
+ draftsCase("drafts-questions", "Four multiple-choice questions on a short reading", ["multiple-choice"], {
598
+ kind: "passage",
599
+ text: MARKET
600
+ }, {
601
+ count: 4,
602
+ level: "A2",
603
+ locale: "en"
604
+ }),
605
+ draftsCase("drafts-cloze", "A cloze on the same reading, from its transcript", ["fill-in-the-blanks"], {
606
+ kind: "transcript",
607
+ text: MARKET
608
+ }, {
609
+ count: 1,
610
+ level: "A2",
611
+ locale: "en",
612
+ instructions: "Blank the verbs."
613
+ }),
614
+ draftsCase("drafts-gaps", "A choose-the-word item on the same reading", ["gap-select"], {
615
+ kind: "passage",
616
+ text: MARKET
617
+ }, {
618
+ count: 1,
619
+ level: "A2",
620
+ locale: "en"
621
+ }),
622
+ draftsCase("drafts-writing", "A writing task that follows on from the reading", ["written-response"], {
623
+ kind: "passage",
624
+ text: MARKET
625
+ }, {
626
+ count: 1,
627
+ level: "A2",
628
+ locale: "en"
629
+ }),
630
+ draftsCase("drafts-video", "A video quiz from timed captions: multiple choice, then dictation, then read-aloud, as many as the video is worth", [
631
+ "multiple-choice",
632
+ "dictation",
633
+ "read-aloud"
634
+ ], {
635
+ kind: "captions",
636
+ cues: MARKET_CAPTIONS
637
+ }, {
638
+ level: "A2",
639
+ locale: "en",
640
+ settings: { "read-aloud": READ_ALOUD_SETTINGS }
641
+ }),
642
+ draftsCase("drafts-script", "The same video from its script alone, with no times, and what the author asked for", [
643
+ "multiple-choice",
644
+ "dictation",
645
+ "read-aloud"
646
+ ], {
647
+ kind: "transcript",
648
+ text: MARKET
649
+ }, {
650
+ level: "A2",
651
+ locale: "en",
652
+ instructions: "Focus on what Maria and her grandmother buy.",
653
+ settings: { "read-aloud": READ_ALOUD_SETTINGS }
654
+ })
655
+ ];
476
656
  }
477
-
478
- // src/ai-check/index.ts
479
- var REFUSALS = [
480
- "malformed",
481
- "empty",
482
- "too-long",
483
- "contradicts-grade",
484
- "reveals-answer",
485
- "misquotes-answer",
486
- "contradicts-marks",
487
- "contradicts-item"
657
+ //#endregion
658
+ //#region src/ai-check/index.ts
659
+ /**
660
+ * A test kit for the prompts behind your AI ports.
661
+ *
662
+ * The SDK cannot test your model, and will not try. What it can do is make the
663
+ * calls a learner's questions would make — on items whose answers it knows —
664
+ * and run the same checks it runs before a learner sees anything. What comes
665
+ * back is a count of what would have been shown and what would have been
666
+ * refused, and why.
667
+ *
668
+ * Run it where you change a prompt or a model, in your own CI, with your own
669
+ * key. It is a separate entry point (`@intellectif/lk-core/ai-check`) because
670
+ * it is for your test run, not for a learner's browser: nothing here is
671
+ * imported by anything a page renders.
672
+ *
673
+ * ```ts
674
+ * import { aiCheckCases, formatAiCheckReport, runAiCheck } from '@intellectif/lk-core/ai-check';
675
+ *
676
+ * const report = await runAiCheck({
677
+ * explain: (request) => callMyModel(EXPLAIN_PROMPT, request),
678
+ * hint: (request) => callMyModel(HINT_PROMPT, request),
679
+ * writingFeedback: (request) => callMyModel(FEEDBACK_PROMPT, request),
680
+ * pronunciationCoaching: (request) => callMyModel(COACHING_PROMPT, request),
681
+ * critique: (request) => callMyModel(CRITIQUE_PROMPT, request),
682
+ * drafts: (request) => callMyModel(DRAFTS_PROMPT, request),
683
+ * });
684
+ * console.log(formatAiCheckReport(report));
685
+ * if (report.refused > 0 || report.errors > 0) {
686
+ * process.exitCode = 1;
687
+ * }
688
+ * ```
689
+ *
690
+ * A refusal is a real failure, not a warning: it is an answer a learner would
691
+ * have asked for and not received. `reveals-answer` on a hint case is the one
692
+ * to take most seriously — that prompt gives answers away. Next come
693
+ * `misquotes-answer` on a writing case — that prompt corrects words the learner
694
+ * never wrote — and `contradicts-marks` on a coaching case: that prompt coaches
695
+ * words the engine heard as right, or sounds it never reported.
696
+ */
697
+ const REFUSALS = [
698
+ "malformed",
699
+ "empty",
700
+ "too-long",
701
+ "contradicts-grade",
702
+ "reveals-answer",
703
+ "misquotes-answer",
704
+ "contradicts-marks",
705
+ "contradicts-item"
488
706
  ];
707
+ /** The port a case is for. */
489
708
  function portFor(ports, one) {
490
- switch (one.request.feature) {
491
- case "explanation":
492
- return ports.explain;
493
- case "hint":
494
- return ports.hint;
495
- case "pronunciation-coaching":
496
- return ports.pronunciationCoaching;
497
- case "item-critique":
498
- return ports.critique;
499
- case "draft-generation":
500
- return ports.drafts;
501
- default:
502
- return ports.writingFeedback;
503
- }
709
+ switch (one.request.feature) {
710
+ case "explanation": return ports.explain;
711
+ case "hint": return ports.hint;
712
+ case "pronunciation-coaching": return ports.pronunciationCoaching;
713
+ case "item-critique": return ports.critique;
714
+ case "draft-generation": return ports.drafts;
715
+ default: return ports.writingFeedback;
716
+ }
504
717
  }
505
- var now = () => Date.now();
718
+ /** Milliseconds, from whichever clock this runtime has. */
719
+ const now = () => Date.now();
720
+ /** Runs one case: calls the port, times it, and checks what came back. */
506
721
  async function runCase(ports, one) {
507
- const started = now();
508
- const port = portFor(ports, one);
509
- if (port === void 0) {
510
- throw new Error(`ai-check: no port for "${one.id}"`);
511
- }
512
- let raw;
513
- try {
514
- raw = await port(one.request);
515
- } catch (error) {
516
- return {
517
- case: one,
518
- ok: false,
519
- error: error instanceof Error ? error.message : String(error),
520
- ms: now() - started
521
- };
522
- }
523
- const ms = now() - started;
524
- if (one.request.feature === "draft-generation") {
525
- let next = 0;
526
- const checked2 = checkAiDrafts(raw, one.request, {
527
- newId: () => {
528
- next += 1;
529
- return `ai-check-${next}`;
530
- }
531
- });
532
- return checked2.ok ? { case: one, ok: true, drafts: checked2.drafts, ms } : refused(one, raw, checked2.refusal, ms);
533
- }
534
- if (one.request.feature === "item-critique") {
535
- const checked2 = checkAiCritique(raw, one.request);
536
- return checked2.ok ? { case: one, ok: true, critique: checked2.critique, ms } : refused(one, raw, checked2.refusal, ms);
537
- }
538
- if (one.request.feature === "pronunciation-coaching") {
539
- const checked2 = checkAiCoaching(raw, one.request);
540
- if (checked2.ok) {
541
- const { text, provenance, usage } = checked2.coaching;
542
- return {
543
- case: one,
544
- ok: true,
545
- result: {
546
- text,
547
- ...provenance !== void 0 ? { provenance } : {},
548
- ...usage !== void 0 ? { usage } : {}
549
- },
550
- coaching: checked2.coaching,
551
- ms
552
- };
553
- }
554
- return refused(one, raw, checked2.refusal, ms);
555
- }
556
- if (one.request.feature === "writing-feedback") {
557
- const checked2 = checkAiWritingFeedback(raw, one.request);
558
- if (checked2.ok) {
559
- const { text, provenance, usage } = checked2.feedback;
560
- return {
561
- case: one,
562
- ok: true,
563
- result: {
564
- text,
565
- ...provenance !== void 0 ? { provenance } : {},
566
- ...usage !== void 0 ? { usage } : {}
567
- },
568
- feedback: checked2.feedback,
569
- ms
570
- };
571
- }
572
- return refused(one, raw, checked2.refusal, ms);
573
- }
574
- const checked = one.request.feature === "explanation" ? checkAiExplanation(raw, one.request) : checkAiHint(raw, one.request);
575
- if (checked.ok) {
576
- return { case: one, ok: true, result: checked.result, ms };
577
- }
578
- return refused(one, raw, checked.refusal, ms);
722
+ const started = now();
723
+ const port = portFor(ports, one);
724
+ if (port === void 0) throw new Error(`ai-check: no port for "${one.id}"`);
725
+ let raw;
726
+ try {
727
+ raw = await port(one.request);
728
+ } catch (error) {
729
+ return {
730
+ case: one,
731
+ ok: false,
732
+ error: error instanceof Error ? error.message : String(error),
733
+ ms: now() - started
734
+ };
735
+ }
736
+ const ms = now() - started;
737
+ if (one.request.feature === "draft-generation") {
738
+ let next = 0;
739
+ const checked = checkAiDrafts(raw, one.request, { newId: () => {
740
+ next += 1;
741
+ return `ai-check-${next}`;
742
+ } });
743
+ return checked.ok ? {
744
+ case: one,
745
+ ok: true,
746
+ drafts: checked.drafts,
747
+ ms
748
+ } : refused(one, raw, checked.refusal, ms);
749
+ }
750
+ if (one.request.feature === "item-critique") {
751
+ const checked = checkAiCritique(raw, one.request);
752
+ return checked.ok ? {
753
+ case: one,
754
+ ok: true,
755
+ critique: checked.critique,
756
+ ms
757
+ } : refused(one, raw, checked.refusal, ms);
758
+ }
759
+ if (one.request.feature === "pronunciation-coaching") {
760
+ const checked = checkAiCoaching(raw, one.request);
761
+ if (checked.ok) {
762
+ const { text, provenance, usage } = checked.coaching;
763
+ return {
764
+ case: one,
765
+ ok: true,
766
+ result: {
767
+ text,
768
+ ...provenance !== void 0 ? { provenance } : {},
769
+ ...usage !== void 0 ? { usage } : {}
770
+ },
771
+ coaching: checked.coaching,
772
+ ms
773
+ };
774
+ }
775
+ return refused(one, raw, checked.refusal, ms);
776
+ }
777
+ if (one.request.feature === "writing-feedback") {
778
+ const checked = checkAiWritingFeedback(raw, one.request);
779
+ if (checked.ok) {
780
+ const { text, provenance, usage } = checked.feedback;
781
+ return {
782
+ case: one,
783
+ ok: true,
784
+ result: {
785
+ text,
786
+ ...provenance !== void 0 ? { provenance } : {},
787
+ ...usage !== void 0 ? { usage } : {}
788
+ },
789
+ feedback: checked.feedback,
790
+ ms
791
+ };
792
+ }
793
+ return refused(one, raw, checked.refusal, ms);
794
+ }
795
+ const checked = one.request.feature === "explanation" ? checkAiExplanation(raw, one.request) : checkAiHint(raw, one.request);
796
+ if (checked.ok) return {
797
+ case: one,
798
+ ok: true,
799
+ result: checked.result,
800
+ ms
801
+ };
802
+ return refused(one, raw, checked.refusal, ms);
579
803
  }
804
+ /** A case whose answer was refused, with the text that came back when there was one to read. */
580
805
  function refused(one, raw, refusal, ms) {
581
- const text = typeof raw?.text === "string" ? raw : void 0;
582
- return {
583
- case: one,
584
- ok: false,
585
- refusal,
586
- ...text !== void 0 ? { result: text } : {},
587
- ms
588
- };
806
+ const text = typeof raw?.text === "string" ? raw : void 0;
807
+ return {
808
+ case: one,
809
+ ok: false,
810
+ refusal,
811
+ ...text !== void 0 ? { result: text } : {},
812
+ ms
813
+ };
589
814
  }
815
+ /**
816
+ * Calls your ports on every case and reports what a learner would have seen.
817
+ *
818
+ * It never throws for a failing case: a port that rejects is an `error` in the
819
+ * report, so one bad call cannot hide the rest.
820
+ */
590
821
  async function runAiCheck(ports, options = {}) {
591
- const all = options.cases ?? aiCheckCases();
592
- const asked = Math.trunc(options.concurrency ?? 1);
593
- const lanes = Number.isFinite(asked) && asked >= 1 ? Math.min(asked, 16) : 1;
594
- const runnable = all.filter((one) => portFor(ports, one) !== void 0);
595
- const results = new Array(runnable.length);
596
- let next = 0;
597
- const lane = async () => {
598
- while (next < runnable.length) {
599
- const mine = next;
600
- next += 1;
601
- const one = runnable[mine];
602
- if (one === void 0) {
603
- return;
604
- }
605
- results[mine] = await runCase(ports, one);
606
- }
607
- };
608
- await Promise.all(Array.from({ length: Math.min(lanes, runnable.length) }, lane));
609
- const byRefusal = Object.fromEntries(REFUSALS.map((reason) => [reason, 0]));
610
- let shown = 0;
611
- let refused2 = 0;
612
- let errors = 0;
613
- for (const result of results) {
614
- if (result.ok) {
615
- shown += 1;
616
- } else if (result.refusal !== void 0) {
617
- refused2 += 1;
618
- byRefusal[result.refusal] += 1;
619
- } else {
620
- errors += 1;
621
- }
622
- }
623
- return {
624
- total: results.length,
625
- shown,
626
- refused: refused2,
627
- errors,
628
- skipped: all.length - runnable.length,
629
- byRefusal,
630
- results
631
- };
822
+ const all = options.cases ?? aiCheckCases();
823
+ const asked = Math.trunc(options.concurrency ?? 1);
824
+ const lanes = Number.isFinite(asked) && asked >= 1 ? Math.min(asked, 16) : 1;
825
+ const runnable = all.filter((one) => portFor(ports, one) !== void 0);
826
+ const results = new Array(runnable.length);
827
+ let next = 0;
828
+ const lane = async () => {
829
+ while (next < runnable.length) {
830
+ const mine = next;
831
+ next += 1;
832
+ const one = runnable[mine];
833
+ if (one === void 0) return;
834
+ results[mine] = await runCase(ports, one);
835
+ }
836
+ };
837
+ await Promise.all(Array.from({ length: Math.min(lanes, runnable.length) }, lane));
838
+ const byRefusal = Object.fromEntries(REFUSALS.map((reason) => [reason, 0]));
839
+ let shown = 0;
840
+ let refused = 0;
841
+ let errors = 0;
842
+ for (const result of results) if (result.ok) shown += 1;
843
+ else if (result.refusal !== void 0) {
844
+ refused += 1;
845
+ byRefusal[result.refusal] += 1;
846
+ } else errors += 1;
847
+ return {
848
+ total: results.length,
849
+ shown,
850
+ refused,
851
+ errors,
852
+ skipped: all.length - runnable.length,
853
+ byRefusal,
854
+ results
855
+ };
632
856
  }
857
+ /**
858
+ * The report as a few lines for a CI log: the counts, then every case that
859
+ * failed, with what came back.
860
+ *
861
+ * The refused text is printed — this is your own test run, not a learner's
862
+ * screen, and a hint that gives the answer away is only fixable if you can
863
+ * read it.
864
+ */
633
865
  function formatAiCheckReport(report) {
634
- const lines = [];
635
- const slowest = report.results.reduce((worst, one) => Math.max(worst, one.ms), 0);
636
- lines.push(
637
- `ai-check: ${report.shown}/${report.total} shown, ${report.refused} refused, ${report.errors} failed${report.skipped > 0 ? `, ${report.skipped} skipped (no port)` : ""} \u2014 slowest ${slowest} ms`
638
- );
639
- for (const reason of REFUSALS) {
640
- const count = report.byRefusal[reason];
641
- if (count > 0) {
642
- lines.push(` ${reason}: ${count}`);
643
- }
644
- }
645
- for (const result of report.results) {
646
- if (result.ok) {
647
- continue;
648
- }
649
- const why = result.refusal ?? `port failed (${result.error ?? "no message"})`;
650
- lines.push(` \u2717 ${result.case.id} [${result.case.feature}] ${result.case.about}: ${why}`);
651
- if (result.result !== void 0) {
652
- lines.push(` ${result.result.text.replace(/\s+/g, " ").slice(0, 200)}`);
653
- }
654
- }
655
- return lines.join("\n");
866
+ const lines = [];
867
+ const slowest = report.results.reduce((worst, one) => Math.max(worst, one.ms), 0);
868
+ lines.push(`ai-check: ${report.shown}/${report.total} shown, ${report.refused} refused, ${report.errors} failed${report.skipped > 0 ? `, ${report.skipped} skipped (no port)` : ""} — slowest ${slowest} ms`);
869
+ for (const reason of REFUSALS) {
870
+ const count = report.byRefusal[reason];
871
+ if (count > 0) lines.push(` ${reason}: ${count}`);
872
+ }
873
+ for (const result of report.results) {
874
+ if (result.ok) continue;
875
+ const why = result.refusal ?? `port failed (${result.error ?? "no message"})`;
876
+ lines.push(` ✗ ${result.case.id} [${result.case.feature}] ${result.case.about}: ${why}`);
877
+ if (result.result !== void 0) lines.push(` ${result.result.text.replace(/\s+/g, " ").slice(0, 200)}`);
878
+ }
879
+ return lines.join("\n");
656
880
  }
657
- export {
658
- aiCheckCases,
659
- formatAiCheckReport,
660
- runAiCheck
661
- };
881
+ //#endregion
882
+ export { aiCheckCases, formatAiCheckReport, runAiCheck };
883
+
662
884
  //# sourceMappingURL=ai-check.js.map