@vue-skuilder/db 0.2.27 → 0.2.29
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.
- package/dist/classroomDB-DLTtLZct.d.cts +86 -0
- package/dist/classroomDB-DLTtLZct.d.ts +86 -0
- package/dist/{contentSource-LPf044hY.d.ts → contentSource-B6FrSihy.d.cts} +282 -99
- package/dist/{contentSource-D3c1fMAk.d.cts → contentSource-CqJmbOZN.d.ts} +282 -99
- package/dist/core/index.d.cts +16 -92
- package/dist/core/index.d.ts +16 -92
- package/dist/core/index.js +607 -179
- package/dist/core/index.js.map +1 -1
- package/dist/core/index.mjs +606 -179
- package/dist/core/index.mjs.map +1 -1
- package/dist/{dataLayerProvider-DaAootVV.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +2 -8
- package/dist/{dataLayerProvider-CeLiFbHv.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +2 -8
- package/dist/diagnostics/index.d.cts +443 -0
- package/dist/diagnostics/index.d.ts +443 -0
- package/dist/diagnostics/index.js +932 -0
- package/dist/diagnostics/index.js.map +1 -0
- package/dist/diagnostics/index.mjs +881 -0
- package/dist/diagnostics/index.mjs.map +1 -0
- package/dist/impl/couch/index.d.cts +13 -3
- package/dist/impl/couch/index.d.ts +13 -3
- package/dist/impl/couch/index.js +605 -179
- package/dist/impl/couch/index.js.map +1 -1
- package/dist/impl/couch/index.mjs +605 -179
- package/dist/impl/couch/index.mjs.map +1 -1
- package/dist/impl/static/index.d.cts +11 -5
- package/dist/impl/static/index.d.ts +11 -5
- package/dist/impl/static/index.js +602 -185
- package/dist/impl/static/index.js.map +1 -1
- package/dist/impl/static/index.mjs +602 -185
- package/dist/impl/static/index.mjs.map +1 -1
- package/dist/{index-BkBJlGDX.d.ts → index-CVGehe_t.d.ts} +1 -1
- package/dist/{index-D7WdMDAs.d.cts → index-Ktg72jKb.d.cts} +1 -1
- package/dist/index.d.cts +73 -11
- package/dist/index.d.ts +73 -11
- package/dist/index.js +696 -200
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +683 -200
- package/dist/index.mjs.map +1 -1
- package/dist/{types-DjiFOZxJ.d.cts → types-D0oQeJAi.d.cts} +1 -1
- package/dist/{types-uJ2Xn3_X.d.ts → types-dXWfyz9B.d.ts} +1 -1
- package/dist/{types-legacy-CrwyZIvI.d.cts → types-legacy-BkOYOR6U.d.cts} +1 -1
- package/dist/{types-legacy-CrwyZIvI.d.ts → types-legacy-BkOYOR6U.d.ts} +1 -1
- package/dist/util/packer/index.d.cts +3 -3
- package/dist/util/packer/index.d.ts +3 -3
- package/package.json +15 -3
- package/src/core/interfaces/contentSource.ts +7 -0
- package/src/core/interfaces/dataLayerProvider.ts +3 -8
- package/src/core/navigators/Pipeline.ts +149 -14
- package/src/core/navigators/PipelineAssembler.ts +19 -40
- package/src/core/navigators/PipelineDebugger.ts +74 -17
- package/src/core/navigators/SrsDebugger.ts +37 -12
- package/src/core/navigators/defaults.ts +29 -5
- package/src/core/navigators/filters/WeightedFilter.ts +5 -1
- package/src/core/navigators/filters/eloDistance.ts +261 -76
- package/src/core/navigators/filters/hierarchyDefinition.ts +5 -1
- package/src/core/navigators/filters/index.ts +2 -2
- package/src/core/navigators/filters/interferenceMitigator.ts +5 -1
- package/src/core/navigators/filters/relativePriority.ts +5 -1
- package/src/core/navigators/filters/types.ts +24 -1
- package/src/core/navigators/filters/userTagPreference.ts +5 -1
- package/src/core/navigators/generators/elo.ts +23 -53
- package/src/core/navigators/generators/srs.ts +27 -124
- package/src/core/navigators/index.ts +32 -5
- package/src/core/navigators/pipelinePlan.ts +245 -0
- package/src/core/navigators/regulators.ts +230 -0
- package/src/core/types/studySession.ts +40 -0
- package/src/diagnostics/dataset.ts +242 -0
- package/src/diagnostics/derive.ts +555 -0
- package/src/diagnostics/index.ts +27 -0
- package/src/diagnostics/loader.ts +194 -0
- package/src/diagnostics/pipeline.ts +236 -0
- package/src/diagnostics/text.ts +265 -0
- package/src/impl/couch/PouchDataLayerProvider.ts +0 -23
- package/src/impl/couch/courseDB.ts +13 -0
- package/src/impl/static/StaticDataLayerProvider.ts +0 -11
- package/src/impl/static/courseDB.ts +9 -0
- package/src/index.ts +4 -0
- package/src/study/SessionController.ts +76 -2
- package/src/study/SessionOverlay.ts +7 -4
- package/tests/core/navigators/PipelineAssembler.test.ts +20 -5
- package/tests/core/navigators/eloDistanceFilter.test.ts +9 -9
- package/tsup.config.ts +1 -0
|
@@ -0,0 +1,555 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Derivations over a `LearnerDataset`: pure functions that views, text
|
|
3
|
+
* exports, and (later) detectors share. Ported from LettersPractice's admin
|
|
4
|
+
* service, with LP's domain knowledge moved behind `DiagnosticsInterpreters`.
|
|
5
|
+
*
|
|
6
|
+
* "Now" is always `dataset.asOf`, never the wall clock, so a dump reads the
|
|
7
|
+
* same tomorrow as today.
|
|
8
|
+
*/
|
|
9
|
+
import type {
|
|
10
|
+
SessionEloEvent,
|
|
11
|
+
SessionStateSnapshot,
|
|
12
|
+
StudySessionDoc,
|
|
13
|
+
StudySessionRunSummary,
|
|
14
|
+
} from '../core/types/studySession';
|
|
15
|
+
import type { CardSummary, DatasetRecord, LearnerDataset } from './dataset';
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Course-supplied meaning for the generic views. Every member is optional and
|
|
19
|
+
* has a neutral default.
|
|
20
|
+
*/
|
|
21
|
+
export interface DiagnosticsInterpreters {
|
|
22
|
+
/** Tags that name what a card exercises: shown inline and sorted first. Default: none. */
|
|
23
|
+
isSkillTag?(tag: string): boolean;
|
|
24
|
+
/** Compact display form of a tag. Default: unchanged. */
|
|
25
|
+
shortTag?(tag: string): string;
|
|
26
|
+
/**
|
|
27
|
+
* Numbers to read off a session's state snapshot, by display label.
|
|
28
|
+
* Default: every numeric field up to two levels deep, labelled by its path.
|
|
29
|
+
*/
|
|
30
|
+
snapshotMetrics?(snapshot: SessionStateSnapshot): Record<string, number>;
|
|
31
|
+
/** Which `snapshotMetrics` labels count as progress (for `stalled`). Default: none. */
|
|
32
|
+
progressMetrics?: string[];
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export const isSkillTag = (i: DiagnosticsInterpreters | undefined, tag: string): boolean =>
|
|
36
|
+
i?.isSkillTag?.(tag) ?? false;
|
|
37
|
+
|
|
38
|
+
export const shortTag = (i: DiagnosticsInterpreters | undefined, tag: string): string =>
|
|
39
|
+
i?.shortTag?.(tag) ?? tag;
|
|
40
|
+
|
|
41
|
+
/** Skill tags first, then alphabetical. */
|
|
42
|
+
function bySkillThenName(i: DiagnosticsInterpreters | undefined) {
|
|
43
|
+
return (a: string, b: string): number => {
|
|
44
|
+
const d = Number(isSkillTag(i, b)) - Number(isSkillTag(i, a));
|
|
45
|
+
return d !== 0 ? d : a.localeCompare(b);
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function defaultSnapshotMetrics(snapshot: SessionStateSnapshot): Record<string, number> {
|
|
50
|
+
const out: Record<string, number> = {};
|
|
51
|
+
for (const [k, v] of Object.entries(snapshot)) {
|
|
52
|
+
if (typeof v === 'number') out[k] = v;
|
|
53
|
+
else if (v && typeof v === 'object' && !Array.isArray(v)) {
|
|
54
|
+
for (const [k2, v2] of Object.entries(v as Record<string, unknown>)) {
|
|
55
|
+
if (typeof v2 === 'number') out[`${k}.${k2}`] = v2;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
return out;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// ============================================================================
|
|
63
|
+
// Sessions
|
|
64
|
+
// ============================================================================
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Ways a session failed to do its job. `out-of-content` is LP's `starved`,
|
|
68
|
+
* renamed so it isn't confused with intake starvation (no new cards chosen).
|
|
69
|
+
*/
|
|
70
|
+
export type SessionFlag = 'churned' | 'out-of-content' | 'walked' | 'stalled' | 'grinding';
|
|
71
|
+
|
|
72
|
+
export const SESSION_FLAGS: Record<SessionFlag, { label: string; help: string }> = {
|
|
73
|
+
churned: {
|
|
74
|
+
label: 'Churned',
|
|
75
|
+
help: 'Many pipeline runs relative to cards served: the plan kept being rebuilt rather than consumed.',
|
|
76
|
+
},
|
|
77
|
+
'out-of-content': {
|
|
78
|
+
label: 'Out of content',
|
|
79
|
+
help: 'Ended with time left on the clock: content ran out before the session did.',
|
|
80
|
+
},
|
|
81
|
+
walked: {
|
|
82
|
+
label: 'Walked',
|
|
83
|
+
help: 'Abandoned or never closed, after real time invested. Not a mis-click.',
|
|
84
|
+
},
|
|
85
|
+
stalled: {
|
|
86
|
+
label: 'Stalled',
|
|
87
|
+
help: 'No progress metric moved and ELO was essentially flat. The sitting produced nothing measurable.',
|
|
88
|
+
},
|
|
89
|
+
grinding: {
|
|
90
|
+
label: 'Grinding',
|
|
91
|
+
help: 'Majority-incorrect, or ended with unfinished cards still in the failed queue.',
|
|
92
|
+
},
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
/** First guesses, not measurements: nothing yet records whether a flag was right. */
|
|
96
|
+
export const SESSION_FLAG_THRESHOLDS = {
|
|
97
|
+
/** Runs per card above which a session counts as churned. */
|
|
98
|
+
churnRunsPerCard: 1 / 3,
|
|
99
|
+
/** Minimum cards before churn is meaningful. */
|
|
100
|
+
churnMinCards: 4,
|
|
101
|
+
/** Leftover clock (s) that counts as running out of content. */
|
|
102
|
+
outOfContentSeconds: 20,
|
|
103
|
+
/** Cards below which an abandon reads as a mis-click, not a walk-out. */
|
|
104
|
+
walkMinCards: 2,
|
|
105
|
+
/** |ELO change| below which movement is flat. */
|
|
106
|
+
stallEloEpsilon: 5,
|
|
107
|
+
/** Accuracy below which a session is grinding. */
|
|
108
|
+
grindAccuracy: 0.5,
|
|
109
|
+
};
|
|
110
|
+
|
|
111
|
+
export interface SessionStateRow {
|
|
112
|
+
label: string;
|
|
113
|
+
from: number | null;
|
|
114
|
+
to: number | null;
|
|
115
|
+
delta: number | null;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
export interface SessionSummary {
|
|
119
|
+
doc: StudySessionDoc;
|
|
120
|
+
/** Null while a session is `open`. */
|
|
121
|
+
durationSeconds: number | null;
|
|
122
|
+
accuracy: number | null;
|
|
123
|
+
/** Net learner global-ELO change over the session's ELO events. Null when it has none. */
|
|
124
|
+
eloNet: number | null;
|
|
125
|
+
/** Snapshot metrics at start and end. */
|
|
126
|
+
state: SessionStateRow[];
|
|
127
|
+
flags: SessionFlag[];
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
function stateRows(doc: StudySessionDoc, interp?: DiagnosticsInterpreters): SessionStateRow[] {
|
|
131
|
+
const read = interp?.snapshotMetrics ?? defaultSnapshotMetrics;
|
|
132
|
+
const a = doc.stateAtStart ? read(doc.stateAtStart) : {};
|
|
133
|
+
const b = doc.stateAtEnd ? read(doc.stateAtEnd) : {};
|
|
134
|
+
const labels = [...new Set([...Object.keys(a), ...Object.keys(b)])];
|
|
135
|
+
return labels.map((label) => {
|
|
136
|
+
const from = a[label] ?? null;
|
|
137
|
+
const to = b[label] ?? null;
|
|
138
|
+
return { label, from, to, delta: from !== null && to !== null ? to - from : null };
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function flagSession(
|
|
143
|
+
s: Omit<SessionSummary, 'flags'>,
|
|
144
|
+
interp?: DiagnosticsInterpreters
|
|
145
|
+
): SessionFlag[] {
|
|
146
|
+
const T = SESSION_FLAG_THRESHOLDS;
|
|
147
|
+
const { doc, accuracy, eloNet } = s;
|
|
148
|
+
const flags: SessionFlag[] = [];
|
|
149
|
+
const cards = doc.tally?.cardsPresented ?? 0;
|
|
150
|
+
const runs = doc.runs?.length ?? 0;
|
|
151
|
+
|
|
152
|
+
if (cards >= T.churnMinCards && runs / cards > T.churnRunsPerCard) flags.push('churned');
|
|
153
|
+
|
|
154
|
+
// Only a closed session can run out of content; an abandoned one has time left by definition.
|
|
155
|
+
if (doc.status === 'closed' && (doc.tally?.secondsRemaining ?? 0) > T.outOfContentSeconds) {
|
|
156
|
+
flags.push('out-of-content');
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
if (doc.status === 'open') flags.push('walked');
|
|
160
|
+
else if (doc.status === 'abandoned' && cards >= T.walkMinCards) flags.push('walked');
|
|
161
|
+
|
|
162
|
+
// Needs something measurable, else every session without snapshots or ELO events would flag.
|
|
163
|
+
const progress = s.state.filter((r) => interp?.progressMetrics?.includes(r.label));
|
|
164
|
+
const measurable = eloNet !== null || progress.some((r) => r.delta !== null);
|
|
165
|
+
if (
|
|
166
|
+
cards > 0 &&
|
|
167
|
+
measurable &&
|
|
168
|
+
progress.every((r) => (r.delta ?? 0) === 0) &&
|
|
169
|
+
Math.abs(eloNet ?? 0) < T.stallEloEpsilon
|
|
170
|
+
) {
|
|
171
|
+
flags.push('stalled');
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
if (
|
|
175
|
+
(accuracy !== null && accuracy < T.grindAccuracy && cards > 0) ||
|
|
176
|
+
(doc.tally?.failedQRemaining ?? 0) > 0
|
|
177
|
+
) {
|
|
178
|
+
flags.push('grinding');
|
|
179
|
+
}
|
|
180
|
+
return flags;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
export function summarizeSession(
|
|
184
|
+
doc: StudySessionDoc,
|
|
185
|
+
interp?: DiagnosticsInterpreters
|
|
186
|
+
): SessionSummary {
|
|
187
|
+
const start = Date.parse(doc.startTime);
|
|
188
|
+
const end = doc.endTime ? Date.parse(doc.endTime) : NaN;
|
|
189
|
+
const durationSeconds =
|
|
190
|
+
Number.isNaN(start) || Number.isNaN(end) ? null : Math.round((end - start) / 1000);
|
|
191
|
+
|
|
192
|
+
const responses = doc.tally?.responses ?? 0;
|
|
193
|
+
const accuracy = responses > 0 ? (doc.tally?.correct ?? 0) / responses : null;
|
|
194
|
+
|
|
195
|
+
const events = doc.eloEvents ?? [];
|
|
196
|
+
const eloNet = events.length
|
|
197
|
+
? events.reduce((n, e) => n + (e.global.after - e.global.before), 0)
|
|
198
|
+
: null;
|
|
199
|
+
|
|
200
|
+
const base = { doc, durationSeconds, accuracy, eloNet, state: stateRows(doc, interp) };
|
|
201
|
+
return { ...base, flags: flagSession(base, interp) };
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** Every session in the dataset, newest first. */
|
|
205
|
+
export function summarizeSessions(
|
|
206
|
+
ds: LearnerDataset,
|
|
207
|
+
interp?: DiagnosticsInterpreters
|
|
208
|
+
): SessionSummary[] {
|
|
209
|
+
return ds.sessions.map((d) => summarizeSession(d, interp)).reverse();
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
// ============================================================================
|
|
213
|
+
// Session timeline
|
|
214
|
+
// ============================================================================
|
|
215
|
+
|
|
216
|
+
/** A `SessionEloEvent` reshaped for one response row: deltas precomputed, tags as a sorted array. */
|
|
217
|
+
export interface ResponseEloDelta {
|
|
218
|
+
userScore: number;
|
|
219
|
+
global: { before: number; after: number; delta: number };
|
|
220
|
+
card?: { before: number; after: number; delta: number };
|
|
221
|
+
/** `score: null` is a count-only exposure that moves count, not ELO. */
|
|
222
|
+
tags: Array<{ tag: string; before: number; after: number; delta: number; score: number | null }>;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
export interface TimelineResponse {
|
|
226
|
+
kind: 'response';
|
|
227
|
+
at: string;
|
|
228
|
+
cardId: string;
|
|
229
|
+
/** Absent when the dataset has no course slice. */
|
|
230
|
+
card?: CardSummary;
|
|
231
|
+
tags: string[];
|
|
232
|
+
questionType?: string;
|
|
233
|
+
isCorrect: boolean | null;
|
|
234
|
+
timeSpentMs: number;
|
|
235
|
+
priorAttempts: number | null;
|
|
236
|
+
userAnswer: unknown;
|
|
237
|
+
/**
|
|
238
|
+
* The ELO exchange this response produced, joined from `eloEvents` by card
|
|
239
|
+
* and nearest time. Absent on retries (only first attempts move ELO), on
|
|
240
|
+
* events in flight at close, and on sessions predating ELO events.
|
|
241
|
+
*/
|
|
242
|
+
elo?: ResponseEloDelta;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
export interface TimelineRun {
|
|
246
|
+
kind: 'run';
|
|
247
|
+
at: string;
|
|
248
|
+
run: StudySessionRunSummary;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* Responses and pipeline runs in one time-ordered stream: a replan firing
|
|
253
|
+
* between two failures is the thing worth seeing, and a per-card pivot can't
|
|
254
|
+
* show sequence.
|
|
255
|
+
*/
|
|
256
|
+
export type TimelineEntry = TimelineResponse | TimelineRun;
|
|
257
|
+
|
|
258
|
+
export interface SessionDetail {
|
|
259
|
+
summary: SessionSummary;
|
|
260
|
+
timeline: TimelineEntry[];
|
|
261
|
+
/** The tally claims more responses than records stamped with this session were found. */
|
|
262
|
+
responsesMissing: boolean;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
function toResponseEloDelta(
|
|
266
|
+
ev: SessionEloEvent,
|
|
267
|
+
interp?: DiagnosticsInterpreters
|
|
268
|
+
): ResponseEloDelta {
|
|
269
|
+
const order = bySkillThenName(interp);
|
|
270
|
+
const tags = Object.entries(ev.tags ?? {})
|
|
271
|
+
.map(([tag, t]) => ({
|
|
272
|
+
tag,
|
|
273
|
+
before: t.before,
|
|
274
|
+
after: t.after,
|
|
275
|
+
delta: t.after - t.before,
|
|
276
|
+
score: t.score,
|
|
277
|
+
}))
|
|
278
|
+
.sort((a, b) => order(a.tag, b.tag));
|
|
279
|
+
return {
|
|
280
|
+
userScore: ev.userScore,
|
|
281
|
+
global: {
|
|
282
|
+
before: ev.global.before,
|
|
283
|
+
after: ev.global.after,
|
|
284
|
+
delta: ev.global.after - ev.global.before,
|
|
285
|
+
},
|
|
286
|
+
...(ev.card
|
|
287
|
+
? {
|
|
288
|
+
card: {
|
|
289
|
+
before: ev.card.before,
|
|
290
|
+
after: ev.card.after,
|
|
291
|
+
delta: ev.card.after - ev.card.before,
|
|
292
|
+
},
|
|
293
|
+
}
|
|
294
|
+
: {}),
|
|
295
|
+
tags,
|
|
296
|
+
};
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/**
|
|
300
|
+
* Attach each ELO event to its response. The event carries no record id, so
|
|
301
|
+
* join by card and nearest time, using each response at most once.
|
|
302
|
+
*/
|
|
303
|
+
function attachEloEvents(
|
|
304
|
+
responses: TimelineResponse[],
|
|
305
|
+
events: SessionEloEvent[],
|
|
306
|
+
interp?: DiagnosticsInterpreters
|
|
307
|
+
): void {
|
|
308
|
+
const used = new Set<number>();
|
|
309
|
+
for (const ev of events) {
|
|
310
|
+
const evT = Date.parse(ev.at);
|
|
311
|
+
let best = -1;
|
|
312
|
+
let bestGap = Infinity;
|
|
313
|
+
responses.forEach((r, i) => {
|
|
314
|
+
if (used.has(i) || r.cardId !== ev.cardId) return;
|
|
315
|
+
const gap = Math.abs(Date.parse(r.at) - evT);
|
|
316
|
+
if (gap < bestGap) {
|
|
317
|
+
bestGap = gap;
|
|
318
|
+
best = i;
|
|
319
|
+
}
|
|
320
|
+
});
|
|
321
|
+
if (best >= 0) {
|
|
322
|
+
used.add(best);
|
|
323
|
+
responses[best].elo = toResponseEloDelta(ev, interp);
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
function byTime(a: { at: string }, b: { at: string }): number {
|
|
329
|
+
const ta = Date.parse(a.at);
|
|
330
|
+
const tb = Date.parse(b.at);
|
|
331
|
+
if (Number.isNaN(ta) || Number.isNaN(tb)) return a.at.localeCompare(b.at);
|
|
332
|
+
return ta - tb;
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/** One session's summary and interleaved timeline, or null if the dataset has no such session. */
|
|
336
|
+
export function sessionDetail(
|
|
337
|
+
ds: LearnerDataset,
|
|
338
|
+
sessionId: string,
|
|
339
|
+
interp?: DiagnosticsInterpreters
|
|
340
|
+
): SessionDetail | null {
|
|
341
|
+
const doc = ds.sessions.find((s) => s.sessionId === sessionId);
|
|
342
|
+
if (!doc) return null;
|
|
343
|
+
|
|
344
|
+
const responses: TimelineResponse[] = [];
|
|
345
|
+
for (const h of ds.cardHistories) {
|
|
346
|
+
const card = ds.cards?.get(h.cardID);
|
|
347
|
+
for (const r of h.records) {
|
|
348
|
+
if (r.sessionId !== sessionId) continue;
|
|
349
|
+
responses.push({
|
|
350
|
+
kind: 'response',
|
|
351
|
+
at: r.timeStamp,
|
|
352
|
+
cardId: h.cardID,
|
|
353
|
+
...(card ? { card, questionType: card.questionType } : {}),
|
|
354
|
+
tags: card ? [...card.tags].sort(bySkillThenName(interp)) : [],
|
|
355
|
+
isCorrect: typeof r.isCorrect === 'boolean' ? r.isCorrect : null,
|
|
356
|
+
timeSpentMs: r.timeSpent ?? 0,
|
|
357
|
+
priorAttempts: typeof r.priorAttemps === 'number' ? r.priorAttemps : null,
|
|
358
|
+
userAnswer: r.userAnswer,
|
|
359
|
+
});
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
if (doc.eloEvents?.length) attachEloEvents(responses, doc.eloEvents, interp);
|
|
363
|
+
|
|
364
|
+
const runs: TimelineRun[] = (doc.runs ?? []).map((run) => ({ kind: 'run', at: run.at, run }));
|
|
365
|
+
const timeline: TimelineEntry[] = [...runs, ...responses].sort(byTime);
|
|
366
|
+
|
|
367
|
+
return {
|
|
368
|
+
summary: summarizeSession(doc, interp),
|
|
369
|
+
timeline,
|
|
370
|
+
responsesMissing: (doc.tally?.responses ?? 0) > responses.length,
|
|
371
|
+
};
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/** Per-tag rollup of what a session served. */
|
|
375
|
+
export interface ServedTagStat {
|
|
376
|
+
tag: string;
|
|
377
|
+
/** Responses carrying this tag (a response with several tags counts toward each). */
|
|
378
|
+
responses: number;
|
|
379
|
+
correct: number;
|
|
380
|
+
incorrect: number;
|
|
381
|
+
/** correct / graded; null when nothing gradeable was served. */
|
|
382
|
+
accuracy: number | null;
|
|
383
|
+
totalTimeMs: number;
|
|
384
|
+
/** Distinct cards carrying this tag. */
|
|
385
|
+
cards: number;
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
/** Skill tags first, then most-served. */
|
|
389
|
+
export function servedTags(
|
|
390
|
+
timeline: TimelineEntry[],
|
|
391
|
+
interp?: DiagnosticsInterpreters
|
|
392
|
+
): ServedTagStat[] {
|
|
393
|
+
const byTag = new Map<
|
|
394
|
+
string,
|
|
395
|
+
{
|
|
396
|
+
responses: number;
|
|
397
|
+
correct: number;
|
|
398
|
+
incorrect: number;
|
|
399
|
+
totalTimeMs: number;
|
|
400
|
+
cards: Set<string>;
|
|
401
|
+
}
|
|
402
|
+
>();
|
|
403
|
+
for (const e of timeline) {
|
|
404
|
+
if (e.kind !== 'response') continue;
|
|
405
|
+
for (const tag of e.tags) {
|
|
406
|
+
let s = byTag.get(tag);
|
|
407
|
+
if (!s) {
|
|
408
|
+
s = { responses: 0, correct: 0, incorrect: 0, totalTimeMs: 0, cards: new Set() };
|
|
409
|
+
byTag.set(tag, s);
|
|
410
|
+
}
|
|
411
|
+
s.responses += 1;
|
|
412
|
+
s.totalTimeMs += e.timeSpentMs;
|
|
413
|
+
s.cards.add(e.cardId);
|
|
414
|
+
if (e.isCorrect === true) s.correct += 1;
|
|
415
|
+
else if (e.isCorrect === false) s.incorrect += 1;
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
return [...byTag.entries()]
|
|
419
|
+
.map(([tag, s]) => {
|
|
420
|
+
const graded = s.correct + s.incorrect;
|
|
421
|
+
return {
|
|
422
|
+
tag,
|
|
423
|
+
responses: s.responses,
|
|
424
|
+
correct: s.correct,
|
|
425
|
+
incorrect: s.incorrect,
|
|
426
|
+
accuracy: graded > 0 ? s.correct / graded : null,
|
|
427
|
+
totalTimeMs: s.totalTimeMs,
|
|
428
|
+
cards: s.cards.size,
|
|
429
|
+
};
|
|
430
|
+
})
|
|
431
|
+
.sort((a, b) => {
|
|
432
|
+
const d = Number(isSkillTag(interp, b.tag)) - Number(isSkillTag(interp, a.tag));
|
|
433
|
+
if (d !== 0) return d;
|
|
434
|
+
if (b.responses !== a.responses) return b.responses - a.responses;
|
|
435
|
+
return a.tag.localeCompare(b.tag);
|
|
436
|
+
});
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
/**
|
|
440
|
+
* A session's net global-ELO move split into wins and losses, so an
|
|
441
|
+
* accuracy/ELO mismatch (many small wins, a few big losses) is legible.
|
|
442
|
+
*/
|
|
443
|
+
export interface EloLedger {
|
|
444
|
+
count: number;
|
|
445
|
+
net: number;
|
|
446
|
+
gained: number;
|
|
447
|
+
lost: number;
|
|
448
|
+
wins: number;
|
|
449
|
+
losses: number;
|
|
450
|
+
}
|
|
451
|
+
|
|
452
|
+
export function eloLedger(timeline: TimelineEntry[]): EloLedger | null {
|
|
453
|
+
const ledger: EloLedger = { count: 0, net: 0, gained: 0, lost: 0, wins: 0, losses: 0 };
|
|
454
|
+
for (const e of timeline) {
|
|
455
|
+
if (e.kind !== 'response' || !e.elo) continue;
|
|
456
|
+
const g = e.elo.global.delta;
|
|
457
|
+
ledger.count += 1;
|
|
458
|
+
ledger.net += g;
|
|
459
|
+
if (g > 0) {
|
|
460
|
+
ledger.gained += g;
|
|
461
|
+
ledger.wins += 1;
|
|
462
|
+
} else if (g < 0) {
|
|
463
|
+
ledger.lost += g;
|
|
464
|
+
ledger.losses += 1;
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
return ledger.count ? ledger : null;
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
// ============================================================================
|
|
471
|
+
// Card dossiers
|
|
472
|
+
// ============================================================================
|
|
473
|
+
|
|
474
|
+
/** Fails at or above which an unmoved card ELO counts as frozen. */
|
|
475
|
+
const FROZEN_FAIL_THRESHOLD = 3;
|
|
476
|
+
|
|
477
|
+
/** Everything recorded about one card for one learner. */
|
|
478
|
+
export interface CardDossier {
|
|
479
|
+
cardId: string;
|
|
480
|
+
/** Absent when the dataset has no course slice. */
|
|
481
|
+
card?: CardSummary;
|
|
482
|
+
records: DatasetRecord[];
|
|
483
|
+
lapses: number;
|
|
484
|
+
streak: number;
|
|
485
|
+
bestIntervalSeconds: number;
|
|
486
|
+
attempts: number;
|
|
487
|
+
fails: number;
|
|
488
|
+
firstSeen: string | null;
|
|
489
|
+
lastSeen: string | null;
|
|
490
|
+
totalTimeMs: number;
|
|
491
|
+
/** Earliest pending review; `overdue` is as of `dataset.asOf`. */
|
|
492
|
+
pendingReview: { reviewTime: string; overdue: boolean } | null;
|
|
493
|
+
cardElo: number | null;
|
|
494
|
+
cardEloCount: number | null;
|
|
495
|
+
/** Failed, and holding an overdue review. */
|
|
496
|
+
stuck: boolean;
|
|
497
|
+
/** Failed repeatedly, yet the card's ELO has fewer updates than failures. */
|
|
498
|
+
frozenElo: boolean;
|
|
499
|
+
/** Time sunk × (fails + 1): grind-heavy, low-payoff cards first. For sorting only. */
|
|
500
|
+
painScore: number;
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
/** One dossier per card the learner has history with, most painful first. */
|
|
504
|
+
export function cardDossiers(ds: LearnerDataset): CardDossier[] {
|
|
505
|
+
const asOf = Date.parse(ds.asOf);
|
|
506
|
+
const pending = new Map<string, string>();
|
|
507
|
+
for (const s of ds.scheduled) {
|
|
508
|
+
const t = String(s.reviewTime);
|
|
509
|
+
const prev = pending.get(s.cardId);
|
|
510
|
+
if (!prev || t < prev) pending.set(s.cardId, t);
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
return ds.cardHistories
|
|
514
|
+
.map((h): CardDossier => {
|
|
515
|
+
const card = ds.cards?.get(h.cardID);
|
|
516
|
+
const fails = h.records.filter((r) => r.isCorrect === false).length;
|
|
517
|
+
const totalTimeMs = h.records.reduce((n, r) => n + (r.timeSpent ?? 0), 0);
|
|
518
|
+
const reviewTime = pending.get(h.cardID);
|
|
519
|
+
const pendingReview = reviewTime
|
|
520
|
+
? { reviewTime, overdue: Date.parse(reviewTime) <= asOf }
|
|
521
|
+
: null;
|
|
522
|
+
const cardElo = card?.elo?.global?.score ?? null;
|
|
523
|
+
const cardEloCount = card?.elo?.global?.count ?? null;
|
|
524
|
+
return {
|
|
525
|
+
cardId: h.cardID,
|
|
526
|
+
...(card ? { card } : {}),
|
|
527
|
+
records: h.records,
|
|
528
|
+
lapses: h.lapses ?? 0,
|
|
529
|
+
streak: h.streak ?? 0,
|
|
530
|
+
bestIntervalSeconds: h.bestInterval ?? 0,
|
|
531
|
+
attempts: h.records.length,
|
|
532
|
+
fails,
|
|
533
|
+
firstSeen: h.records[0]?.timeStamp ?? null,
|
|
534
|
+
lastSeen: h.records[h.records.length - 1]?.timeStamp ?? null,
|
|
535
|
+
totalTimeMs,
|
|
536
|
+
pendingReview,
|
|
537
|
+
cardElo,
|
|
538
|
+
cardEloCount,
|
|
539
|
+
stuck: fails > 0 && !!pendingReview?.overdue,
|
|
540
|
+
frozenElo: fails >= FROZEN_FAIL_THRESHOLD && cardEloCount !== null && cardEloCount < fails,
|
|
541
|
+
painScore: totalTimeMs * (fails + 1),
|
|
542
|
+
};
|
|
543
|
+
})
|
|
544
|
+
.sort((a, b) => b.painScore - a.painScore);
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
/** A record's global performance, whether stored as a number or a per-tag map. */
|
|
548
|
+
export function recordPerformance(r: DatasetRecord): number | null {
|
|
549
|
+
const p = r.performance as unknown;
|
|
550
|
+
if (typeof p === 'number') return p;
|
|
551
|
+
if (p && typeof p === 'object' && typeof (p as { _global?: unknown })._global === 'number') {
|
|
552
|
+
return (p as { _global: number })._global;
|
|
553
|
+
}
|
|
554
|
+
return null;
|
|
555
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Learner diagnostics: read one learner's records into a portable dataset,
|
|
3
|
+
* and derive what the admin views, text exports, and detectors show.
|
|
4
|
+
*
|
|
5
|
+
* `fetchLearnerDump` reads from couch (admin rights; basic auth or the
|
|
6
|
+
* browser's session cookie). `parseLearnerDump` reads the same shape from a
|
|
7
|
+
* file. `fromDump` indexes either. The derivations are pure over the indexed
|
|
8
|
+
* dataset. Nothing here imports Pouch or constructs a user, so this entry is
|
|
9
|
+
* safe in the browser, node, and the CLI.
|
|
10
|
+
*
|
|
11
|
+
* Design notes: `agent/diagnostics/` in the framework repo.
|
|
12
|
+
*/
|
|
13
|
+
export * from './dataset';
|
|
14
|
+
export * from './loader';
|
|
15
|
+
export * from './derive';
|
|
16
|
+
export * from './text';
|
|
17
|
+
export * from './pipeline';
|
|
18
|
+
export type {
|
|
19
|
+
SessionEloEvent,
|
|
20
|
+
SessionStateSnapshot,
|
|
21
|
+
StudySessionDoc,
|
|
22
|
+
StudySessionRunCard,
|
|
23
|
+
StudySessionRunCardTrail,
|
|
24
|
+
StudySessionRunSummary,
|
|
25
|
+
} from '../core/types/studySession';
|
|
26
|
+
export type { RegulatorName, RegulatorReading } from '../core/navigators/regulators';
|
|
27
|
+
export type { FilterKind } from '../core/navigators/filters/types';
|