@vue-skuilder/db 0.2.28 → 0.2.30
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/{contentSource-DpQqTG3m.d.cts → contentSource-B6FrSihy.d.cts} +218 -2
- package/dist/{contentSource-BoFBwvYa.d.ts → contentSource-CqJmbOZN.d.ts} +218 -2
- package/dist/core/index.d.cts +13 -90
- package/dist/core/index.d.ts +13 -90
- package/dist/core/index.js +621 -179
- package/dist/core/index.js.map +1 -1
- package/dist/core/index.mjs +620 -179
- package/dist/core/index.mjs.map +1 -1
- package/dist/{dataLayerProvider-D_LJT3F4.d.ts → dataLayerProvider-B9_UCvkR.d.ts} +1 -1
- package/dist/{dataLayerProvider-Dl3cAAvQ.d.cts → dataLayerProvider-DUxDqMtZ.d.cts} +1 -1
- package/dist/diagnostics/index.d.cts +79 -6
- package/dist/diagnostics/index.d.ts +79 -6
- package/dist/diagnostics/index.js +158 -4
- package/dist/diagnostics/index.js.map +1 -1
- package/dist/diagnostics/index.mjs +156 -4
- package/dist/diagnostics/index.mjs.map +1 -1
- package/dist/impl/couch/index.d.cts +11 -2
- package/dist/impl/couch/index.d.ts +11 -2
- package/dist/impl/couch/index.js +619 -179
- package/dist/impl/couch/index.js.map +1 -1
- package/dist/impl/couch/index.mjs +619 -179
- package/dist/impl/couch/index.mjs.map +1 -1
- package/dist/impl/static/index.d.cts +8 -2
- package/dist/impl/static/index.d.ts +8 -2
- package/dist/impl/static/index.js +616 -179
- package/dist/impl/static/index.js.map +1 -1
- package/dist/impl/static/index.mjs +616 -179
- package/dist/impl/static/index.mjs.map +1 -1
- package/dist/index.d.cts +66 -5
- package/dist/index.d.ts +66 -5
- package/dist/index.js +669 -180
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +656 -180
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -3
- package/src/core/interfaces/contentSource.ts +7 -0
- package/src/core/navigators/Pipeline.ts +145 -13
- package/src/core/navigators/PipelineAssembler.ts +19 -40
- package/src/core/navigators/PipelineDebugger.ts +11 -2
- 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 +320 -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 +31 -5
- package/src/core/navigators/pipelinePlan.ts +245 -0
- package/src/core/navigators/regulators.ts +230 -0
- package/src/core/types/studySession.ts +3 -0
- package/src/diagnostics/dataset.ts +13 -2
- package/src/diagnostics/index.ts +3 -0
- package/src/diagnostics/loader.ts +5 -2
- package/src/diagnostics/pipeline.ts +236 -0
- package/src/diagnostics/text.ts +26 -3
- package/src/impl/couch/courseDB.ts +13 -0
- package/src/impl/static/courseDB.ts +9 -0
- package/src/index.ts +4 -0
- package/src/study/SessionController.ts +20 -0
- 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/package.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
7
|
-
"version": "0.2.
|
|
7
|
+
"version": "0.2.30",
|
|
8
8
|
"description": "Database layer for vue-skuilder",
|
|
9
9
|
"main": "dist/index.js",
|
|
10
10
|
"module": "dist/index.mjs",
|
|
@@ -60,7 +60,7 @@
|
|
|
60
60
|
},
|
|
61
61
|
"dependencies": {
|
|
62
62
|
"@nilock2/pouchdb-authentication": "^1.0.2",
|
|
63
|
-
"@vue-skuilder/common": "0.2.
|
|
63
|
+
"@vue-skuilder/common": "0.2.30",
|
|
64
64
|
"cross-fetch": "^4.1.0",
|
|
65
65
|
"moment": "^2.29.4",
|
|
66
66
|
"pouchdb": "^9.0.0",
|
|
@@ -75,5 +75,5 @@
|
|
|
75
75
|
"vite": "^8.0.0",
|
|
76
76
|
"vitest": "^4.1.0"
|
|
77
77
|
},
|
|
78
|
-
"stableVersion": "0.2.
|
|
78
|
+
"stableVersion": "0.2.30"
|
|
79
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,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) {
|
|
@@ -506,6 +535,10 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
506
535
|
const scoredCards = cards;
|
|
507
536
|
cards = cards.filter((c) => c.score > 0);
|
|
508
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
|
+
|
|
509
542
|
// Apply ephemeral hints (one-shot, post-filter)
|
|
510
543
|
const hints = this._ephemeralHints;
|
|
511
544
|
if (hints) {
|
|
@@ -571,7 +604,8 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
571
604
|
result,
|
|
572
605
|
context.userElo,
|
|
573
606
|
hints?? undefined,
|
|
574
|
-
scoredCards
|
|
607
|
+
scoredCards,
|
|
608
|
+
regulators
|
|
575
609
|
);
|
|
576
610
|
captureRun(report);
|
|
577
611
|
} catch (e) {
|
|
@@ -785,6 +819,93 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
785
819
|
return cards;
|
|
786
820
|
}
|
|
787
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
|
+
|
|
788
909
|
/**
|
|
789
910
|
* Build shared context for generator and filters.
|
|
790
911
|
*
|
|
@@ -795,11 +916,12 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
795
916
|
*/
|
|
796
917
|
private async buildContext(): Promise<GeneratorContext & FilterContext> {
|
|
797
918
|
let userElo = 1000; // Default ELO
|
|
919
|
+
let userCourseElo: CourseElo | undefined;
|
|
798
920
|
|
|
799
921
|
try {
|
|
800
922
|
const courseReg = await this.user!.getCourseRegDoc(this.course!.getCourseID());
|
|
801
|
-
|
|
802
|
-
userElo =
|
|
923
|
+
userCourseElo = toCourseElo(courseReg.elo);
|
|
924
|
+
userElo = userCourseElo.global.score;
|
|
803
925
|
} catch (e) {
|
|
804
926
|
logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
|
|
805
927
|
}
|
|
@@ -816,6 +938,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
816
938
|
user: this.user!,
|
|
817
939
|
course: this.course!,
|
|
818
940
|
userElo,
|
|
941
|
+
...(userCourseElo ? { userCourseElo } : {}),
|
|
819
942
|
orchestration,
|
|
820
943
|
};
|
|
821
944
|
}
|
|
@@ -961,7 +1084,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
961
1084
|
const fullPool = cards.slice();
|
|
962
1085
|
|
|
963
1086
|
const context = await this.buildContext();
|
|
964
|
-
for (const filter of this.
|
|
1087
|
+
for (const filter of this.forecastFilters()) {
|
|
965
1088
|
cards = await filter.transform(cards, context);
|
|
966
1089
|
}
|
|
967
1090
|
|
|
@@ -985,6 +1108,15 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
985
1108
|
return opts?.limit ? cards.slice(0, opts.limit) : cards;
|
|
986
1109
|
}
|
|
987
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
|
+
|
|
988
1120
|
/**
|
|
989
1121
|
* Scan every card in the course through the filter chain and report
|
|
990
1122
|
* how many are "well indicated" (score >= threshold) for the current user.
|
|
@@ -1016,7 +1148,7 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
|
|
|
1016
1148
|
const filterBreakdown: Array<{ name: string; wellIndicated: number }> = [];
|
|
1017
1149
|
|
|
1018
1150
|
// Track cumulative filter effects
|
|
1019
|
-
for (const filter of this.
|
|
1151
|
+
for (const filter of this.forecastFilters()) {
|
|
1020
1152
|
cards = await filter.transform(cards, context);
|
|
1021
1153
|
const wi = cards.filter((c) => c.score >= THRESHOLD).length;
|
|
1022
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,6 +70,8 @@ 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;
|
|
@@ -148,6 +152,9 @@ export interface PipelineRunReport {
|
|
|
148
152
|
topGenerated?: RunReportCard;
|
|
149
153
|
};
|
|
150
154
|
|
|
155
|
+
/** The regulator stage's readings: each class's pressure and the multiplier it got. */
|
|
156
|
+
regulators?: RegulatorReading[];
|
|
157
|
+
|
|
151
158
|
/**
|
|
152
159
|
* Summary of the discarded tail of the candidate pool — cards that were
|
|
153
160
|
* generated and scored but neither selected nor retained in `cards`.
|
|
@@ -293,7 +300,8 @@ export function buildRunReport(
|
|
|
293
300
|
userElo?: number,
|
|
294
301
|
hints?: ReplanHints,
|
|
295
302
|
/** Post-filter cards before zero-scored ones are dropped. Defaults to `allCards`. */
|
|
296
|
-
scoredCards?: WeightedCard[]
|
|
303
|
+
scoredCards?: WeightedCard[],
|
|
304
|
+
regulators?: RegulatorReading[]
|
|
297
305
|
): Omit<PipelineRunReport, 'runId' | 'timestamp'> {
|
|
298
306
|
const selectedIds = new Set(selectedCards.map((c) => c.cardId));
|
|
299
307
|
|
|
@@ -307,7 +315,7 @@ export function buildRunReport(
|
|
|
307
315
|
origin: getOrigin(card),
|
|
308
316
|
generator: card.provenance[0]?.strategyName || card.provenance[0]?.strategy,
|
|
309
317
|
finalScore: card.score,
|
|
310
|
-
cardElo: parseCardElo(card.provenance),
|
|
318
|
+
cardElo: card.cardElo ?? parseCardElo(card.provenance),
|
|
311
319
|
provenance: card.provenance,
|
|
312
320
|
tags: card.tags,
|
|
313
321
|
selected: selectedIds.has(card.cardId),
|
|
@@ -406,6 +414,7 @@ export function buildRunReport(
|
|
|
406
414
|
cards,
|
|
407
415
|
unselectedNew,
|
|
408
416
|
discardedTail,
|
|
417
|
+
...(regulators ? { regulators } : {}),
|
|
409
418
|
};
|
|
410
419
|
}
|
|
411
420
|
|
|
@@ -2,15 +2,16 @@
|
|
|
2
2
|
// SRS BACKLOG DEBUGGER
|
|
3
3
|
// ============================================================================
|
|
4
4
|
//
|
|
5
|
-
// A tiny module-level capture of
|
|
6
|
-
//
|
|
7
|
-
//
|
|
8
|
-
//
|
|
9
|
-
//
|
|
10
|
-
//
|
|
5
|
+
// A tiny module-level capture of per-run review backlog state, so the live
|
|
6
|
+
// session overlay can show how much runway remains before reviews out-compete
|
|
7
|
+
// the current (boosted) new/prescribed cards: the review-mass multiplier is
|
|
8
|
+
// exponential and uncapped, so it always has headroom to climb further — the
|
|
9
|
+
// question is just how large the backlog's mass needs to get before it crosses
|
|
10
|
+
// whatever the competing boosts currently sit at.
|
|
11
11
|
//
|
|
12
|
-
//
|
|
13
|
-
//
|
|
12
|
+
// The SRS generator captures counts each run; the pipeline's regulator stage
|
|
13
|
+
// then patches in the review mass and the multiplier (noteReviewPressure).
|
|
14
|
+
// Keyed by course, latest wins; the overlay reads it via the controller's
|
|
14
15
|
// getDebugSnapshot(). No DB load on the read path.
|
|
15
16
|
//
|
|
16
17
|
// ============================================================================
|
|
@@ -22,13 +23,18 @@ export interface SrsBacklogDebug {
|
|
|
22
23
|
scheduledTotal: number;
|
|
23
24
|
/** Reviews eligible (due) right now. */
|
|
24
25
|
dueNow: number;
|
|
25
|
-
/** Healthy
|
|
26
|
+
/** Healthy review mass (card-equivalents); the multiplier is ×1.0 at or below it. */
|
|
26
27
|
healthyBacklog: number;
|
|
27
|
-
/**
|
|
28
|
+
/**
|
|
29
|
+
* Review mass: the due reviews' filtered scores against a reference, each at
|
|
30
|
+
* most 1. Set by the regulator stage; null until it has run.
|
|
31
|
+
*/
|
|
32
|
+
reviewMass: number | null;
|
|
33
|
+
/** Multiplier the regulator stage applied to every due review this run (>= 1.0, unbounded). */
|
|
28
34
|
backlogMultiplier: number;
|
|
29
|
-
/** Exponential growth-rate base the multiplier climbs by per multiple of
|
|
35
|
+
/** Exponential growth-rate base the multiplier climbs by per multiple of healthy mass in excess. */
|
|
30
36
|
backlogGrowthRate: number;
|
|
31
|
-
/** Highest review score
|
|
37
|
+
/** Highest review urgency score from the SRS generator (before filters and regulators); null if none due. */
|
|
32
38
|
topReviewScore: number | null;
|
|
33
39
|
/** Human-readable time until the next review comes due, or null if some are due now. */
|
|
34
40
|
nextDueIn: string | null;
|
|
@@ -43,6 +49,25 @@ export function captureSrsBacklog(snapshot: SrsBacklogDebug): void {
|
|
|
43
49
|
snapshots.set(snapshot.courseId, snapshot);
|
|
44
50
|
}
|
|
45
51
|
|
|
52
|
+
/**
|
|
53
|
+
* Called by the pipeline's regulator stage once per run: the review mass and
|
|
54
|
+
* the multiplier it set. Patches the course's latest SRS snapshot.
|
|
55
|
+
*/
|
|
56
|
+
export function noteReviewPressure(
|
|
57
|
+
courseId: string,
|
|
58
|
+
pressure: { mass: number; healthyMass: number; rate: number; multiplier: number }
|
|
59
|
+
): void {
|
|
60
|
+
const snapshot = snapshots.get(courseId);
|
|
61
|
+
if (!snapshot) return;
|
|
62
|
+
snapshots.set(courseId, {
|
|
63
|
+
...snapshot,
|
|
64
|
+
reviewMass: pressure.mass,
|
|
65
|
+
healthyBacklog: pressure.healthyMass,
|
|
66
|
+
backlogGrowthRate: pressure.rate,
|
|
67
|
+
backlogMultiplier: pressure.multiplier,
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
|
|
46
71
|
/** Current backlog snapshot for every course seen, newest-first. */
|
|
47
72
|
export function getSrsBacklogDebug(): SrsBacklogDebug[] {
|
|
48
73
|
return [...snapshots.values()].sort((a, b) => b.timestamp - a.timestamp);
|
|
@@ -3,7 +3,7 @@ import { Pipeline } from './Pipeline';
|
|
|
3
3
|
import CompositeGenerator from './generators/CompositeGenerator';
|
|
4
4
|
import ELONavigator from './generators/elo';
|
|
5
5
|
import SRSNavigator from './generators/srs';
|
|
6
|
-
import {
|
|
6
|
+
import EloDistanceFilter, { DEFAULT_ELO_DISTANCE_CONFIG } from './filters/eloDistance';
|
|
7
7
|
import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
|
|
8
8
|
import { DocType } from '../types/types-legacy';
|
|
9
9
|
import type { CourseDBInterface, UserDBInterface } from '../interfaces';
|
|
@@ -53,13 +53,33 @@ export function createDefaultSrsStrategy(courseId: string): ContentNavigationStr
|
|
|
53
53
|
};
|
|
54
54
|
}
|
|
55
55
|
|
|
56
|
+
/**
|
|
57
|
+
* Create default ELO distance filter strategy data. The assembler adds it to
|
|
58
|
+
* any pipeline whose strategy docs declare no `eloDistance` filter.
|
|
59
|
+
*
|
|
60
|
+
* @param courseId - The course ID to associate with this strategy
|
|
61
|
+
* @returns Strategy data for the default ELO distance filter (default curve)
|
|
62
|
+
*/
|
|
63
|
+
export function createDefaultEloDistanceStrategy(courseId: string): ContentNavigationStrategyData {
|
|
64
|
+
return {
|
|
65
|
+
_id: 'NAVIGATION_STRATEGY-eloDistance-default',
|
|
66
|
+
docType: DocType.NAVIGATION_STRATEGY,
|
|
67
|
+
name: 'ELO Distance (default)',
|
|
68
|
+
description: 'Scales every candidate, new or review, by its distance from the learner\'s ELO',
|
|
69
|
+
implementingClass: Navigators.ELO_DISTANCE,
|
|
70
|
+
course: courseId,
|
|
71
|
+
// Explicit, though the filter would default to it anyway: views show what runs.
|
|
72
|
+
serializedData: JSON.stringify(DEFAULT_ELO_DISTANCE_CONFIG),
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
|
|
56
76
|
/**
|
|
57
77
|
* Creates the default navigation pipeline for courses with no configured strategies.
|
|
58
78
|
*
|
|
59
|
-
* Default: Pipeline(Composite(ELO, SRS), [
|
|
60
|
-
* - ELO generator:
|
|
79
|
+
* Default: Pipeline(Composite(ELO, SRS), [ELO distance])
|
|
80
|
+
* - ELO generator: retrieves new cards near the learner's ELO
|
|
61
81
|
* - SRS generator: scores reviews by overdueness and interval recency
|
|
62
|
-
* - ELO distance filter:
|
|
82
|
+
* - ELO distance filter: scales every card by its distance from the learner's ELO
|
|
63
83
|
*
|
|
64
84
|
* This is the canonical default configuration used when:
|
|
65
85
|
* - No navigation strategy documents exist in the course
|
|
@@ -78,7 +98,11 @@ export function createDefaultPipeline(
|
|
|
78
98
|
const srsNavigator = new SRSNavigator(user, course, createDefaultSrsStrategy(courseId));
|
|
79
99
|
|
|
80
100
|
const compositeGenerator = new CompositeGenerator([eloNavigator, srsNavigator]);
|
|
81
|
-
const eloDistanceFilter =
|
|
101
|
+
const eloDistanceFilter = new EloDistanceFilter(
|
|
102
|
+
user,
|
|
103
|
+
course,
|
|
104
|
+
createDefaultEloDistanceStrategy(courseId)
|
|
105
|
+
);
|
|
82
106
|
|
|
83
107
|
return new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
|
|
84
108
|
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { CardFilter, FilterContext } from './types';
|
|
1
|
+
import { CardFilter, FilterContext, FilterKind } from './types';
|
|
2
2
|
import { WeightedCard } from '../index';
|
|
3
3
|
import { LearnableWeight, DEFAULT_LEARNABLE_WEIGHT } from '../../types/contentNavigationStrategy';
|
|
4
4
|
|
|
@@ -18,6 +18,8 @@ import { LearnableWeight, DEFAULT_LEARNABLE_WEIGHT } from '../../types/contentNa
|
|
|
18
18
|
*/
|
|
19
19
|
export class WeightedFilter implements CardFilter {
|
|
20
20
|
public name: string;
|
|
21
|
+
public kind?: FilterKind;
|
|
22
|
+
public liveOnly?: boolean;
|
|
21
23
|
private inner: CardFilter;
|
|
22
24
|
private learnable: LearnableWeight;
|
|
23
25
|
private staticWeight: boolean;
|
|
@@ -31,6 +33,8 @@ export class WeightedFilter implements CardFilter {
|
|
|
31
33
|
) {
|
|
32
34
|
this.inner = inner;
|
|
33
35
|
this.name = inner.name;
|
|
36
|
+
this.kind = inner.kind;
|
|
37
|
+
this.liveOnly = inner.liveOnly;
|
|
34
38
|
this.learnable = learnable;
|
|
35
39
|
this.staticWeight = staticWeight;
|
|
36
40
|
this.strategyId = strategyId;
|