@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
|
@@ -165,4 +165,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
|
|
|
165
165
|
priorAttemps: number;
|
|
166
166
|
}
|
|
167
167
|
|
|
168
|
-
export { type
|
|
168
|
+
export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QuestionRecord as Q, type SkuilderCourseData as S, type Tag as T, type DisplayableData as a, type CardRecord as b, type CardHistory as c, type QualifiedCardID as d, type TagStub as e, DocTypePrefixes as f, type CourseListData as g, type DataShapeData as h, type QuestionData as i, log as l };
|
|
@@ -165,4 +165,4 @@ interface QuestionRecord extends CardRecord, Evaluation {
|
|
|
165
165
|
priorAttemps: number;
|
|
166
166
|
}
|
|
167
167
|
|
|
168
|
-
export { type
|
|
168
|
+
export { type CardData as C, DocType as D, type Field as F, GuestUsername as G, type QuestionRecord as Q, type SkuilderCourseData as S, type Tag as T, type DisplayableData as a, type CardRecord as b, type CardHistory as c, type QualifiedCardID as d, type TagStub as e, DocTypePrefixes as f, type CourseListData as g, type DataShapeData as h, type QuestionData as i, log as l };
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-
|
|
2
|
-
export { C as CouchDBToStaticPacker } from '../../index-
|
|
1
|
+
export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-D0oQeJAi.cjs';
|
|
2
|
+
export { C as CouchDBToStaticPacker } from '../../index-Ktg72jKb.cjs';
|
|
3
3
|
import '@vue-skuilder/common';
|
|
4
|
-
import '../../types-legacy-
|
|
4
|
+
import '../../types-legacy-BkOYOR6U.cjs';
|
|
5
5
|
import 'moment';
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-
|
|
2
|
-
export { C as CouchDBToStaticPacker } from '../../index-
|
|
1
|
+
export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-dXWfyz9B.js';
|
|
2
|
+
export { C as CouchDBToStaticPacker } from '../../index-CVGehe_t.js';
|
|
3
3
|
import '@vue-skuilder/common';
|
|
4
|
-
import '../../types-legacy-
|
|
4
|
+
import '../../types-legacy-BkOYOR6U.js';
|
|
5
5
|
import 'moment';
|
package/package.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
7
|
-
"version": "0.2.
|
|
7
|
+
"version": "0.2.29",
|
|
8
8
|
"description": "Database layer for vue-skuilder",
|
|
9
9
|
"main": "dist/index.js",
|
|
10
10
|
"module": "dist/index.mjs",
|
|
@@ -34,6 +34,18 @@
|
|
|
34
34
|
"types": "./dist/impl/static/index.d.ts",
|
|
35
35
|
"import": "./dist/impl/static/index.mjs",
|
|
36
36
|
"require": "./dist/impl/static/index.js"
|
|
37
|
+
},
|
|
38
|
+
"./diagnostics": {
|
|
39
|
+
"types": "./dist/diagnostics/index.d.ts",
|
|
40
|
+
"import": "./dist/diagnostics/index.mjs",
|
|
41
|
+
"require": "./dist/diagnostics/index.js"
|
|
42
|
+
}
|
|
43
|
+
},
|
|
44
|
+
"typesVersions": {
|
|
45
|
+
"*": {
|
|
46
|
+
"diagnostics": [
|
|
47
|
+
"./dist/diagnostics/index.d.ts"
|
|
48
|
+
]
|
|
37
49
|
}
|
|
38
50
|
},
|
|
39
51
|
"scripts": {
|
|
@@ -48,7 +60,7 @@
|
|
|
48
60
|
},
|
|
49
61
|
"dependencies": {
|
|
50
62
|
"@nilock2/pouchdb-authentication": "^1.0.2",
|
|
51
|
-
"@vue-skuilder/common": "0.2.
|
|
63
|
+
"@vue-skuilder/common": "0.2.29",
|
|
52
64
|
"cross-fetch": "^4.1.0",
|
|
53
65
|
"moment": "^2.29.4",
|
|
54
66
|
"pouchdb": "^9.0.0",
|
|
@@ -63,5 +75,5 @@
|
|
|
63
75
|
"vite": "^8.0.0",
|
|
64
76
|
"vitest": "^4.1.0"
|
|
65
77
|
},
|
|
66
|
-
"stableVersion": "0.2.
|
|
78
|
+
"stableVersion": "0.2.29"
|
|
67
79
|
}
|
|
@@ -92,6 +92,13 @@ export interface StudyContentSource {
|
|
|
92
92
|
* No-op for sources that don't support hints.
|
|
93
93
|
*/
|
|
94
94
|
setEphemeralHints?(hints: ReplanHints): void;
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* A card was just presented. `status` is the session item's (`'new'`,
|
|
98
|
+
* `'review'`, `'failed-new'`, ...). Pipelines use a new card's first
|
|
99
|
+
* presentation to restart their intake valve's clock.
|
|
100
|
+
*/
|
|
101
|
+
notePresented?(card: { cardId: string; courseId: string; status: string }): void;
|
|
95
102
|
}
|
|
96
103
|
// #endregion docs_StudyContentSource
|
|
97
104
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// db/src/core/interfaces.ts
|
|
2
2
|
|
|
3
|
-
import { UserDBInterface
|
|
3
|
+
import { UserDBInterface } from './userDB';
|
|
4
4
|
import { CourseDBInterface, CoursesDBInterface } from './courseDB';
|
|
5
5
|
import { ClassroomDBInterface } from './classroomDB';
|
|
6
6
|
import { AdminDBInterface } from './adminDB';
|
|
@@ -14,13 +14,8 @@ export interface DataLayerProvider {
|
|
|
14
14
|
*/
|
|
15
15
|
getUserDB(): UserDBInterface;
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
* Uses session authentication to verify requesting user is admin
|
|
20
|
-
* @param targetUsername - The username to create a reader for
|
|
21
|
-
* @throws Error if requesting user is not 'admin'
|
|
22
|
-
*/
|
|
23
|
-
createUserReaderForUser(targetUsername: string): Promise<UserDBReader>;
|
|
17
|
+
// Reading another learner's records (admin): see `@vue-skuilder/db/diagnostics`
|
|
18
|
+
// (`fetchLearnerDump`). A second UserDB would replace the logged-in one.
|
|
24
19
|
|
|
25
20
|
/**
|
|
26
21
|
* Get a course database interface
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { toCourseElo } from '@vue-skuilder/common';
|
|
1
|
+
import { toCourseElo, type CourseElo } from '@vue-skuilder/common';
|
|
2
2
|
import type { CourseDBInterface } from '../interfaces/courseDB';
|
|
3
3
|
import type { UserDBInterface } from '../interfaces/userDB';
|
|
4
4
|
import { ContentNavigator } from './index';
|
|
@@ -10,6 +10,18 @@ import { logger } from '../../util/logger';
|
|
|
10
10
|
import { createOrchestrationContext, OrchestrationContext } from '../orchestration';
|
|
11
11
|
import { captureRun, buildRunReport, registerPipelineForDebug, type GeneratorSummary, type FilterImpact } from './PipelineDebugger';
|
|
12
12
|
import { diversityRerank } from './diversityRerank';
|
|
13
|
+
import {
|
|
14
|
+
applyReading,
|
|
15
|
+
DEFAULT_REGULATOR_CONFIG,
|
|
16
|
+
INTAKE_CLOCK_KEY,
|
|
17
|
+
intakeReading,
|
|
18
|
+
resetIntakeClock,
|
|
19
|
+
reviewMassReading,
|
|
20
|
+
stepIntakeClock,
|
|
21
|
+
type IntakeClockState,
|
|
22
|
+
type RegulatorReading,
|
|
23
|
+
} from './regulators';
|
|
24
|
+
import { noteReviewPressure } from './SrsDebugger';
|
|
13
25
|
|
|
14
26
|
// ============================================================================
|
|
15
27
|
// REPLAN HINTS
|
|
@@ -298,6 +310,14 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
298
310
|
*/
|
|
299
311
|
private _ephemeralHints: ReplanHints | null = null;
|
|
300
312
|
|
|
313
|
+
/**
|
|
314
|
+
* The intake valve's clock (see regulators.ts), loaded from strategy state on
|
|
315
|
+
* first use and kept in memory. Writes are chained so a presentation and a
|
|
316
|
+
* run can't race each other's revision.
|
|
317
|
+
*/
|
|
318
|
+
private _intakeClock: IntakeClockState | null = null;
|
|
319
|
+
private _intakeClockWrite: Promise<void> = Promise.resolve();
|
|
320
|
+
|
|
301
321
|
/**
|
|
302
322
|
* Create a new pipeline.
|
|
303
323
|
*
|
|
@@ -401,13 +421,14 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
401
421
|
}
|
|
402
422
|
}
|
|
403
423
|
generatorSummaries = Array.from(genMap.entries()).map(([name, data]) => {
|
|
404
|
-
|
|
405
|
-
|
|
424
|
+
// Reviews carry `reviewID`; everything else a generator emits is unseen.
|
|
425
|
+
// (Reason text can't tell: the ELO generator's never says "new card".)
|
|
426
|
+
const reviewCount = data.cards.filter((c) => c.reviewID).length;
|
|
406
427
|
return {
|
|
407
428
|
name,
|
|
408
429
|
cardCount: data.cards.length,
|
|
409
|
-
newCount:
|
|
410
|
-
reviewCount
|
|
430
|
+
newCount: data.cards.length - reviewCount,
|
|
431
|
+
reviewCount,
|
|
411
432
|
topScore: Math.max(...data.cards.map((c) => c.score), 0),
|
|
412
433
|
};
|
|
413
434
|
});
|
|
@@ -459,6 +480,10 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
459
480
|
.map((c) => c.cardId)
|
|
460
481
|
);
|
|
461
482
|
const filterImpacts: FilterImpact[] = [];
|
|
483
|
+
// Scores as generated, so regulators can read the filters' net effect on each card.
|
|
484
|
+
const generatedScores = new Map(cards.map((c) => [c.cardId, c.score]));
|
|
485
|
+
// Cards a gate penalized: not ready, so regulators won't lift them.
|
|
486
|
+
const gated = new Set<string>();
|
|
462
487
|
// [perf] parked 2026-05 (pipeline-docs-workup) — uncomment to re-measure
|
|
463
488
|
// const filterTimings: string[] = [];
|
|
464
489
|
for (const filter of this.filters) {
|
|
@@ -472,13 +497,17 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
472
497
|
let boosted = 0, penalized = 0, passed = 0;
|
|
473
498
|
const removed = beforeCount - cards.length;
|
|
474
499
|
|
|
500
|
+
// Undeclared filters count as gates (see CardFilter.kind).
|
|
501
|
+
const kind = filter.kind ?? 'gate';
|
|
475
502
|
for (const card of cards) {
|
|
476
503
|
const before = beforeScores.get(card.cardId) ?? 0;
|
|
477
504
|
if (card.score > before) boosted++;
|
|
478
|
-
else if (card.score < before)
|
|
479
|
-
|
|
505
|
+
else if (card.score < before) {
|
|
506
|
+
penalized++;
|
|
507
|
+
if (kind === 'gate') gated.add(card.cardId);
|
|
508
|
+
} else passed++;
|
|
480
509
|
}
|
|
481
|
-
filterImpacts.push({ name: filter.name, boosted, penalized, passed, removed });
|
|
510
|
+
filterImpacts.push({ name: filter.name, kind, boosted, penalized, passed, removed });
|
|
482
511
|
|
|
483
512
|
// Report prescribed card fate through each filter
|
|
484
513
|
if (prescribedIds.size > 0) {
|
|
@@ -501,9 +530,15 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
501
530
|
logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeScores.size} → ${cards.length} cards (↑${boosted} ↓${penalized} =${passed})`);
|
|
502
531
|
}
|
|
503
532
|
|
|
504
|
-
// Remove zero-score cards (hard filtered)
|
|
533
|
+
// Remove zero-score cards (hard filtered). The debug report still wants
|
|
534
|
+
// them: they're the answer to "which filter sank this card?"
|
|
535
|
+
const scoredCards = cards;
|
|
505
536
|
cards = cards.filter((c) => c.score > 0);
|
|
506
537
|
|
|
538
|
+
// Regulators: class-level pressure between reviews and new cards, from the
|
|
539
|
+
// filtered scores (see regulators.ts). Before hints, so session intent wins.
|
|
540
|
+
const regulators = await this.regulate(cards, generatedScores, gated);
|
|
541
|
+
|
|
507
542
|
// Apply ephemeral hints (one-shot, post-filter)
|
|
508
543
|
const hints = this._ephemeralHints;
|
|
509
544
|
if (hints) {
|
|
@@ -568,7 +603,9 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
568
603
|
cards,
|
|
569
604
|
result,
|
|
570
605
|
context.userElo,
|
|
571
|
-
hints?? undefined
|
|
606
|
+
hints?? undefined,
|
|
607
|
+
scoredCards,
|
|
608
|
+
regulators
|
|
572
609
|
);
|
|
573
610
|
captureRun(report);
|
|
574
611
|
} catch (e) {
|
|
@@ -782,6 +819,93 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
782
819
|
return cards;
|
|
783
820
|
}
|
|
784
821
|
|
|
822
|
+
/**
|
|
823
|
+
* The regulator stage: measure each class's pressure and scale it.
|
|
824
|
+
*
|
|
825
|
+
* - Review mass: every due review's SRS urgency times the filters' net
|
|
826
|
+
* effect on it.
|
|
827
|
+
* - Intake: servable hours since a new card was presented, applied only to
|
|
828
|
+
* eligible new cards (no gate penalized them). With none eligible, the
|
|
829
|
+
* clock freezes.
|
|
830
|
+
*
|
|
831
|
+
* Mutates `cards` in place; returns the readings for the run report.
|
|
832
|
+
*/
|
|
833
|
+
private async regulate(
|
|
834
|
+
cards: WeightedCard[],
|
|
835
|
+
generatedScores: ReadonlyMap<string, number>,
|
|
836
|
+
gated: Set<string>
|
|
837
|
+
): Promise<RegulatorReading[]> {
|
|
838
|
+
const config = DEFAULT_REGULATOR_CONFIG;
|
|
839
|
+
const reviews = cards.filter((c) => c.reviewID);
|
|
840
|
+
const newCards = cards.filter((c) => !c.reviewID);
|
|
841
|
+
const eligibleNew = newCards.filter((c) => !gated.has(c.cardId));
|
|
842
|
+
|
|
843
|
+
const mass = reviewMassReading(reviews, generatedScores, config.reviewMass);
|
|
844
|
+
applyReading(reviews, mass);
|
|
845
|
+
noteReviewPressure(this.course!.getCourseID(), {
|
|
846
|
+
mass: mass.urgency,
|
|
847
|
+
healthyMass: config.reviewMass.healthyMass,
|
|
848
|
+
rate: config.reviewMass.rate,
|
|
849
|
+
multiplier: mass.multiplier,
|
|
850
|
+
});
|
|
851
|
+
|
|
852
|
+
const now = Date.now();
|
|
853
|
+
const clock = await this.loadIntakeClock(now);
|
|
854
|
+
const stepped = stepIntakeClock(clock, now, eligibleNew.length);
|
|
855
|
+
if (stepped !== clock) this.saveIntakeClock(stepped);
|
|
856
|
+
const intake = intakeReading(
|
|
857
|
+
stepped,
|
|
858
|
+
now,
|
|
859
|
+
{ eligibleNew: eligibleNew.length, newCandidates: newCards.length },
|
|
860
|
+
config.intake
|
|
861
|
+
);
|
|
862
|
+
applyReading(eligibleNew, intake);
|
|
863
|
+
|
|
864
|
+
logger.info(
|
|
865
|
+
`[Pipeline:regulators] review mass ${mass.urgency.toFixed(1)} over ${reviews.length} due → ` +
|
|
866
|
+
`×${mass.multiplier.toFixed(2)}; intake ${intake.urgency.toFixed(1)}h, ` +
|
|
867
|
+
`${eligibleNew.length}/${newCards.length} new eligible → ×${intake.multiplier.toFixed(2)}`
|
|
868
|
+
);
|
|
869
|
+
return [mass, intake];
|
|
870
|
+
}
|
|
871
|
+
|
|
872
|
+
/**
|
|
873
|
+
* A card was presented. A new card's first presentation discharges the
|
|
874
|
+
* intake valve: its clock restarts. Called by the SessionController.
|
|
875
|
+
*/
|
|
876
|
+
notePresented(card: { cardId: string; courseId: string; status: string }): void {
|
|
877
|
+
if (card.status !== 'new' || card.courseId !== this.course?.getCourseID()) return;
|
|
878
|
+
this.saveIntakeClock(resetIntakeClock(Date.now()));
|
|
879
|
+
}
|
|
880
|
+
|
|
881
|
+
private async loadIntakeClock(nowMs: number): Promise<IntakeClockState> {
|
|
882
|
+
if (this._intakeClock) return this._intakeClock;
|
|
883
|
+
let stored: IntakeClockState | null = null;
|
|
884
|
+
try {
|
|
885
|
+
stored = await this.user!.getStrategyState<IntakeClockState>(
|
|
886
|
+
this.course!.getCourseID(),
|
|
887
|
+
INTAKE_CLOCK_KEY
|
|
888
|
+
);
|
|
889
|
+
} catch (e) {
|
|
890
|
+
logger.warn(`[Pipeline:regulators] Could not read the intake clock: ${e}`);
|
|
891
|
+
}
|
|
892
|
+
if (stored) {
|
|
893
|
+
this._intakeClock = stored;
|
|
894
|
+
} else {
|
|
895
|
+
// No clock yet: start it now.
|
|
896
|
+
this.saveIntakeClock(resetIntakeClock(nowMs));
|
|
897
|
+
}
|
|
898
|
+
return this._intakeClock!;
|
|
899
|
+
}
|
|
900
|
+
|
|
901
|
+
private saveIntakeClock(state: IntakeClockState): void {
|
|
902
|
+
this._intakeClock = state;
|
|
903
|
+
const courseId = this.course!.getCourseID();
|
|
904
|
+
this._intakeClockWrite = this._intakeClockWrite
|
|
905
|
+
.then(() => this.user!.putStrategyState(courseId, INTAKE_CLOCK_KEY, state))
|
|
906
|
+
.catch((e) => logger.warn(`[Pipeline:regulators] Could not save the intake clock: ${e}`));
|
|
907
|
+
}
|
|
908
|
+
|
|
785
909
|
/**
|
|
786
910
|
* Build shared context for generator and filters.
|
|
787
911
|
*
|
|
@@ -792,11 +916,12 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
792
916
|
*/
|
|
793
917
|
private async buildContext(): Promise<GeneratorContext & FilterContext> {
|
|
794
918
|
let userElo = 1000; // Default ELO
|
|
919
|
+
let userCourseElo: CourseElo | undefined;
|
|
795
920
|
|
|
796
921
|
try {
|
|
797
922
|
const courseReg = await this.user!.getCourseRegDoc(this.course!.getCourseID());
|
|
798
|
-
|
|
799
|
-
userElo =
|
|
923
|
+
userCourseElo = toCourseElo(courseReg.elo);
|
|
924
|
+
userElo = userCourseElo.global.score;
|
|
800
925
|
} catch (e) {
|
|
801
926
|
logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
|
|
802
927
|
}
|
|
@@ -813,6 +938,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
813
938
|
user: this.user!,
|
|
814
939
|
course: this.course!,
|
|
815
940
|
userElo,
|
|
941
|
+
...(userCourseElo ? { userCourseElo } : {}),
|
|
816
942
|
orchestration,
|
|
817
943
|
};
|
|
818
944
|
}
|
|
@@ -958,7 +1084,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
958
1084
|
const fullPool = cards.slice();
|
|
959
1085
|
|
|
960
1086
|
const context = await this.buildContext();
|
|
961
|
-
for (const filter of this.
|
|
1087
|
+
for (const filter of this.forecastFilters()) {
|
|
962
1088
|
cards = await filter.transform(cards, context);
|
|
963
1089
|
}
|
|
964
1090
|
|
|
@@ -982,6 +1108,15 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
982
1108
|
return opts?.limit ? cards.slice(0, opts.limit) : cards;
|
|
983
1109
|
}
|
|
984
1110
|
|
|
1111
|
+
/**
|
|
1112
|
+
* The filters a forecast or card-space scan applies. Those start every card at
|
|
1113
|
+
* 1.0 without a generator, so they skip `liveOnly` filters (ELO distance),
|
|
1114
|
+
* which only make sense against generator scores.
|
|
1115
|
+
*/
|
|
1116
|
+
private forecastFilters(): CardFilter[] {
|
|
1117
|
+
return this.filters.filter((f) => !f.liveOnly);
|
|
1118
|
+
}
|
|
1119
|
+
|
|
985
1120
|
/**
|
|
986
1121
|
* Scan every card in the course through the filter chain and report
|
|
987
1122
|
* how many are "well indicated" (score >= threshold) for the current user.
|
|
@@ -1013,7 +1148,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
1013
1148
|
const filterBreakdown: Array<{ name: string; wellIndicated: number }> = [];
|
|
1014
1149
|
|
|
1015
1150
|
// Track cumulative filter effects
|
|
1016
|
-
for (const filter of this.
|
|
1151
|
+
for (const filter of this.forecastFilters()) {
|
|
1017
1152
|
cards = await filter.transform(cards, context);
|
|
1018
1153
|
const wi = cards.filter((c) => c.score >= THRESHOLD).length;
|
|
1019
1154
|
filterBreakdown.push({ name: filter.name, wellIndicated: wi });
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
|
|
2
|
-
import { ContentNavigator
|
|
2
|
+
import { ContentNavigator } from './index';
|
|
3
3
|
import type { CardFilter } from './filters/types';
|
|
4
4
|
import { WeightedFilter } from './filters/WeightedFilter';
|
|
5
5
|
import type { CardGenerator } from './generators/types';
|
|
@@ -8,7 +8,7 @@ import { logger } from '../../util/logger';
|
|
|
8
8
|
import type { CourseDBInterface } from '../interfaces/courseDB';
|
|
9
9
|
import type { UserDBInterface } from '../interfaces/userDB';
|
|
10
10
|
import CompositeGenerator from './generators/CompositeGenerator';
|
|
11
|
-
import {
|
|
11
|
+
import { planPipeline } from './pipelinePlan';
|
|
12
12
|
|
|
13
13
|
// ============================================================================
|
|
14
14
|
// PIPELINE ASSEMBLER
|
|
@@ -23,7 +23,7 @@ import { createDefaultEloStrategy, createDefaultSrsStrategy } from './defaults';
|
|
|
23
23
|
// 3. Easy unit testing without DB mocking
|
|
24
24
|
//
|
|
25
25
|
// Pipeline assembly:
|
|
26
|
-
// 1.
|
|
26
|
+
// 1. Plan: classify by role, add defaults, order filters (pipelinePlan.ts)
|
|
27
27
|
// 2. Instantiate generator(s) - wrap multiple in CompositeGenerator
|
|
28
28
|
// 3. Instantiate filters
|
|
29
29
|
// 4. Return Pipeline(generator, filters)
|
|
@@ -66,11 +66,11 @@ export class PipelineAssembler {
|
|
|
66
66
|
/**
|
|
67
67
|
* Assembles a navigation pipeline from strategy documents.
|
|
68
68
|
*
|
|
69
|
-
* 1.
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
69
|
+
* 1. Plans: classifies by role, adds default ELO/SRS and ELO distance, orders filters
|
|
70
|
+
* (`planPipeline`)
|
|
71
|
+
* 2. Instantiates generators - wraps multiple in CompositeGenerator
|
|
72
|
+
* 3. Instantiates filters
|
|
73
|
+
* 4. Returns Pipeline(generator, filters)
|
|
74
74
|
*
|
|
75
75
|
* @param input - Strategy documents plus user/course interfaces
|
|
76
76
|
* @returns Assembled pipeline and any warnings
|
|
@@ -88,35 +88,19 @@ export class PipelineAssembler {
|
|
|
88
88
|
};
|
|
89
89
|
}
|
|
90
90
|
|
|
91
|
-
//
|
|
92
|
-
|
|
93
|
-
const
|
|
94
|
-
|
|
95
|
-
for (const
|
|
96
|
-
if (
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
} else {
|
|
101
|
-
// Unknown strategy type — skip with warning
|
|
102
|
-
warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
|
|
91
|
+
// Classify, add defaults, and order filters: the same plan the admin
|
|
92
|
+
// pipeline view renders.
|
|
93
|
+
const plan = planPipeline(strategies, course.getCourseID());
|
|
94
|
+
warnings.push(...plan.warnings);
|
|
95
|
+
for (const n of [...plan.generators, ...plan.filters]) {
|
|
96
|
+
if (n.origin === 'assembler-default') {
|
|
97
|
+
logger.debug(
|
|
98
|
+
`[PipelineAssembler] No ${n.implementingClass} ${n.role} configured, adding default`
|
|
99
|
+
);
|
|
103
100
|
}
|
|
104
101
|
}
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
// Custom generators (e.g., prescribed) supplement but don't replace them.
|
|
108
|
-
const courseId = course.getCourseID();
|
|
109
|
-
const hasElo = generatorStrategies.some((s) => s.implementingClass === Navigators.ELO);
|
|
110
|
-
const hasSrs = generatorStrategies.some((s) => s.implementingClass === Navigators.SRS);
|
|
111
|
-
|
|
112
|
-
if (!hasElo) {
|
|
113
|
-
logger.debug('[PipelineAssembler] No ELO generator configured, adding default');
|
|
114
|
-
generatorStrategies.push(createDefaultEloStrategy(courseId));
|
|
115
|
-
}
|
|
116
|
-
if (!hasSrs) {
|
|
117
|
-
logger.debug('[PipelineAssembler] No SRS generator configured, adding default');
|
|
118
|
-
generatorStrategies.push(createDefaultSrsStrategy(courseId));
|
|
119
|
-
}
|
|
102
|
+
const generatorStrategies = plan.generators.map((g) => g.strategy);
|
|
103
|
+
const sortedFilterStrategies = plan.filters.map((f) => f.strategy);
|
|
120
104
|
|
|
121
105
|
if (generatorStrategies.length === 0) {
|
|
122
106
|
warnings.push('No generator strategy found');
|
|
@@ -147,11 +131,6 @@ export class PipelineAssembler {
|
|
|
147
131
|
// Instantiate filters
|
|
148
132
|
const filters: CardFilter[] = [];
|
|
149
133
|
|
|
150
|
-
// Sort filters alphabetically for deterministic ordering
|
|
151
|
-
const sortedFilterStrategies = [...filterStrategies].sort((a, b) =>
|
|
152
|
-
a.name.localeCompare(b.name)
|
|
153
|
-
);
|
|
154
|
-
|
|
155
134
|
for (const filterStrategy of sortedFilterStrategies) {
|
|
156
135
|
try {
|
|
157
136
|
const nav = await ContentNavigator.create(user, course, filterStrategy);
|
|
@@ -10,6 +10,8 @@ import {
|
|
|
10
10
|
import { logger } from '../../util/logger';
|
|
11
11
|
import type { Pipeline, CardSpaceDiagnosis, PipelineForecaster } from './Pipeline';
|
|
12
12
|
import type { ReplanHints } from './generators/types';
|
|
13
|
+
import type { FilterKind } from './filters/types';
|
|
14
|
+
import type { RegulatorReading } from './regulators';
|
|
13
15
|
|
|
14
16
|
/**
|
|
15
17
|
* Captured reference to the most recently created Pipeline instance.
|
|
@@ -68,12 +70,28 @@ export interface GeneratorSummary {
|
|
|
68
70
|
*/
|
|
69
71
|
export interface FilterImpact {
|
|
70
72
|
name: string;
|
|
73
|
+
/** Effective kind: undeclared filters count as gates. Absent on runs before 0.2.29. */
|
|
74
|
+
kind?: FilterKind;
|
|
71
75
|
boosted: number;
|
|
72
76
|
penalized: number;
|
|
73
77
|
passed: number;
|
|
74
78
|
removed: number;
|
|
75
79
|
}
|
|
76
80
|
|
|
81
|
+
/** One card as retained in a {@link PipelineRunReport}. */
|
|
82
|
+
export interface RunReportCard {
|
|
83
|
+
cardId: string;
|
|
84
|
+
courseId: string;
|
|
85
|
+
origin: 'new' | 'review' | 'unknown';
|
|
86
|
+
generator?: string;
|
|
87
|
+
finalScore: number;
|
|
88
|
+
/** Card's ELO (parsed from ELO generator provenance, if available) */
|
|
89
|
+
cardElo?: number;
|
|
90
|
+
provenance: StrategyContribution[];
|
|
91
|
+
tags?: string[];
|
|
92
|
+
selected: boolean;
|
|
93
|
+
}
|
|
94
|
+
|
|
77
95
|
/**
|
|
78
96
|
* Complete record of a single pipeline execution.
|
|
79
97
|
*/
|
|
@@ -117,18 +135,25 @@ export interface PipelineRunReport {
|
|
|
117
135
|
* rather than retained verbatim — each retained card carries a multi-KB
|
|
118
136
|
* provenance trail, and the tail is typically hundreds of cards per run.
|
|
119
137
|
*/
|
|
120
|
-
cards:
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
138
|
+
cards: RunReportCard[];
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* The two unselected non-review cards most worth explaining when a run
|
|
142
|
+
* picks no new content. Non-review means no `reviewID`, so prescribed and
|
|
143
|
+
* required cards count (their `origin` reads `'unknown'`).
|
|
144
|
+
*
|
|
145
|
+
* - `nextInLine`: highest final score. How close new content came.
|
|
146
|
+
* - `topGenerated`: highest generator score, zero-scored cards included.
|
|
147
|
+
* Its provenance shows which filter sank it. Omitted when it is the same
|
|
148
|
+
* card as `nextInLine`.
|
|
149
|
+
*/
|
|
150
|
+
unselectedNew?: {
|
|
151
|
+
nextInLine?: RunReportCard;
|
|
152
|
+
topGenerated?: RunReportCard;
|
|
153
|
+
};
|
|
154
|
+
|
|
155
|
+
/** The regulator stage's readings: each class's pressure and the multiplier it got. */
|
|
156
|
+
regulators?: RegulatorReading[];
|
|
132
157
|
|
|
133
158
|
/**
|
|
134
159
|
* Summary of the discarded tail of the candidate pool — cards that were
|
|
@@ -273,7 +298,10 @@ export function buildRunReport(
|
|
|
273
298
|
allCards: WeightedCard[],
|
|
274
299
|
selectedCards: WeightedCard[],
|
|
275
300
|
userElo?: number,
|
|
276
|
-
hints?: ReplanHints
|
|
301
|
+
hints?: ReplanHints,
|
|
302
|
+
/** Post-filter cards before zero-scored ones are dropped. Defaults to `allCards`. */
|
|
303
|
+
scoredCards?: WeightedCard[],
|
|
304
|
+
regulators?: RegulatorReading[]
|
|
277
305
|
): Omit<PipelineRunReport, 'runId' | 'timestamp'> {
|
|
278
306
|
const selectedIds = new Set(selectedCards.map((c) => c.cardId));
|
|
279
307
|
|
|
@@ -281,20 +309,20 @@ export function buildRunReport(
|
|
|
281
309
|
// into selected vs not-selected, then retain only the top-N of the
|
|
282
310
|
// non-selected group to bound memory. The remaining low-score tail is
|
|
283
311
|
// summarized rather than kept (see discardedTail).
|
|
284
|
-
const toReport = (card: WeightedCard) => ({
|
|
312
|
+
const toReport = (card: WeightedCard): RunReportCard => ({
|
|
285
313
|
cardId: card.cardId,
|
|
286
314
|
courseId: card.courseId,
|
|
287
315
|
origin: getOrigin(card),
|
|
288
316
|
generator: card.provenance[0]?.strategyName || card.provenance[0]?.strategy,
|
|
289
317
|
finalScore: card.score,
|
|
290
|
-
cardElo: parseCardElo(card.provenance),
|
|
318
|
+
cardElo: card.cardElo ?? parseCardElo(card.provenance),
|
|
291
319
|
provenance: card.provenance,
|
|
292
320
|
tags: card.tags,
|
|
293
321
|
selected: selectedIds.has(card.cardId),
|
|
294
322
|
});
|
|
295
323
|
|
|
296
|
-
const selectedReported:
|
|
297
|
-
const nearMissReported:
|
|
324
|
+
const selectedReported: RunReportCard[] = [];
|
|
325
|
+
const nearMissReported: RunReportCard[] = [];
|
|
298
326
|
const discardedTailCards: WeightedCard[] = [];
|
|
299
327
|
|
|
300
328
|
let nonSelectedSeen = 0;
|
|
@@ -341,6 +369,33 @@ export function buildRunReport(
|
|
|
341
369
|
};
|
|
342
370
|
}
|
|
343
371
|
|
|
372
|
+
// Unselected non-review candidates. `nextInLine` ranks by final score, so it
|
|
373
|
+
// comes from `allCards` (post-hints; zero-scored dropped). `topGenerated`
|
|
374
|
+
// ranks by generator score and must see the zero-scored cards too, but not
|
|
375
|
+
// cards a hint excluded: exclusion leaves no provenance to explain them.
|
|
376
|
+
const isUnselectedNew = (c: WeightedCard) => !c.reviewID && !selectedIds.has(c.cardId);
|
|
377
|
+
const generatorScore = (c: WeightedCard) => c.provenance[0]?.score ?? 0;
|
|
378
|
+
const keptIds = new Set(allCards.map((c) => c.cardId));
|
|
379
|
+
const hintExcluded = (c: WeightedCard) => c.score > 0 && !keptIds.has(c.cardId);
|
|
380
|
+
let nextInLine: WeightedCard | undefined;
|
|
381
|
+
for (const c of allCards) {
|
|
382
|
+
if (isUnselectedNew(c) && (!nextInLine || c.score > nextInLine.score)) nextInLine = c;
|
|
383
|
+
}
|
|
384
|
+
let topGenerated: WeightedCard | undefined;
|
|
385
|
+
for (const c of scoredCards ?? allCards) {
|
|
386
|
+
if (!isUnselectedNew(c) || hintExcluded(c)) continue;
|
|
387
|
+
if (!topGenerated || generatorScore(c) > generatorScore(topGenerated)) topGenerated = c;
|
|
388
|
+
}
|
|
389
|
+
const unselectedNew =
|
|
390
|
+
nextInLine || topGenerated
|
|
391
|
+
? {
|
|
392
|
+
...(nextInLine ? { nextInLine: toReport(nextInLine) } : {}),
|
|
393
|
+
...(topGenerated && topGenerated.cardId !== nextInLine?.cardId
|
|
394
|
+
? { topGenerated: toReport(topGenerated) }
|
|
395
|
+
: {}),
|
|
396
|
+
}
|
|
397
|
+
: undefined;
|
|
398
|
+
|
|
344
399
|
const reviewsSelected = selectedCards.filter((c) => getOrigin(c) === 'review').length;
|
|
345
400
|
const newSelected = selectedCards.filter((c) => getOrigin(c) === 'new').length;
|
|
346
401
|
|
|
@@ -357,7 +412,9 @@ export function buildRunReport(
|
|
|
357
412
|
reviewsSelected,
|
|
358
413
|
newSelected,
|
|
359
414
|
cards,
|
|
415
|
+
unselectedNew,
|
|
360
416
|
discardedTail,
|
|
417
|
+
...(regulators ? { regulators } : {}),
|
|
361
418
|
};
|
|
362
419
|
}
|
|
363
420
|
|