learngraph 0.4.0 → 0.7.0

package/dist/types/query/spaced-repetition.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Spaced Repetition Scheduler (SM-2 Algorithm)
+ *
+ * Implements the SuperMemo SM-2 algorithm for optimal review scheduling.
+ * Schedules reviews at increasing intervals based on performance.
+ *
+ * @packageDocumentation
+ */
+import type { SkillId } from '../types/skill.js';
+import type { MasteryState } from '../types/mastery.js';
+import type { GraphStorage } from '../types/storage.js';
+import type { ReviewSchedule, ReviewOptions } from '../types/query.js';
+/**
+ * Default options for review scheduling
+ */
+export declare const REVIEW_DEFAULTS: Required<ReviewOptions>;
+/**
+ * SM-2 algorithm constants
+ */
+export declare const SM2_CONSTANTS: {
+    /** Minimum easiness factor */
+    readonly MIN_EASINESS: 1.3;
+    /** Default easiness factor */
+    readonly DEFAULT_EASINESS: 2.5;
+    /** Maximum easiness factor */
+    readonly MAX_EASINESS: 3.5;
+    /** Initial interval (days) after first review */
+    readonly INITIAL_INTERVAL: 1;
+    /** Second interval (days) after second review */
+    readonly SECOND_INTERVAL: 6;
+};
+/**
+ * Review quality rating (0-5 scale)
+ */
+export type ReviewQuality = 0 | 1 | 2 | 3 | 4 | 5;
+/**
+ * Learner review state
+ */
+export interface ReviewState {
+    /** Mastery states for skills (keyed by skill ID) */
+    masteryStates: Map<SkillId, MasteryState>;
+}
+/**
+ * SM-2 update result
+ */
+export interface SM2Result {
+    /** New easiness factor */
+    easinessFactor: number;
+    /** New interval in days */
+    intervalDays: number;
+    /** Next review date */
+    nextReview: Date;
+    /** Number of successful repetitions */
+    repetitions: number;
+}
+/**
+ * Spaced Repetition Scheduler
+ *
+ * Uses the SM-2 algorithm to schedule optimal review times.
+ * The algorithm adjusts intervals based on recall quality:
+ * - Quality 5: Perfect response
+ * - Quality 4: Correct with hesitation
+ * - Quality 3: Correct with difficulty
+ * - Quality 2: Incorrect but easily recalled
+ * - Quality 1: Incorrect, remembered when shown
+ * - Quality 0: Complete blackout
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new SpacedRepetitionScheduler(storage);
+ *
+ * // Get review schedule
+ * const schedule = await scheduler.getSchedule(learnerState);
+ * console.log(`${schedule.dueNow.length} reviews due now`);
+ *
+ * // Update after a review
+ * const result = scheduler.calculateNextReview(masteryState, 4); // quality 4
+ * console.log(`Next review in ${result.intervalDays} days`);
+ * ```
+ */
+export declare class SpacedRepetitionScheduler {
+    private readonly storage;
+    constructor(storage: GraphStorage);
+    /**
+     * Get the review schedule for a learner
+     *
+     * @param learner - Current learner state
+     * @param options - Schedule options
+     * @returns Review schedule with due and upcoming items
+     */
+    getSchedule(learner: ReviewState, options?: ReviewOptions): Promise<ReviewSchedule>;
+    /**
+     * Calculate the next review interval using SM-2 algorithm
+     *
+     * @param currentState - Current mastery state
+     * @param quality - Review quality (0-5)
+     * @returns Updated SM-2 parameters
+     */
+    calculateNextReview(currentState: MasteryState, quality: ReviewQuality): SM2Result;
+    /**
+     * Convert review quality to mastery update
+     *
+     * @param quality - Review quality (0-5)
+     * @returns Mastery level adjustment
+     */
+    qualityToMasteryAdjustment(quality: ReviewQuality): number;
+    /**
+     * Calculate next review date based on current mastery state
+     */
+    private calculateNextReviewDate;
+    /**
+     * Estimate previous interval from mastery state
+     */
+    private estimatePreviousInterval;
+    /**
+     * Calculate review priority
+     * Higher priority = more urgent to review
+     */
+    private calculatePriority;
+}
+/**
+ * Create a spaced repetition scheduler
+ */
+export declare function createSpacedRepetitionScheduler(storage: GraphStorage): SpacedRepetitionScheduler;
+/**
+ * Standalone SM-2 calculation (for use without storage)
+ *
+ * @param quality - Review quality (0-5)
+ * @param previousEasiness - Previous easiness factor
+ * @param previousInterval - Previous interval in days
+ * @param repetitions - Number of previous successful repetitions
+ * @returns Updated SM-2 parameters
+ */
+export declare function calculateSM2(quality: ReviewQuality, previousEasiness?: number, previousInterval?: number, repetitions?: number): SM2Result;
+//# sourceMappingURL=spaced-repetition.d.ts.map

package/dist/types/query/spaced-repetition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaced-repetition.d.ts","sourceRoot":"","sources":["../../../src/query/spaced-repetition.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAc,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEnF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,aAAa,CAInD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;IACxB,8BAA8B;;IAE9B,8BAA8B;;IAE9B,8BAA8B;;IAE9B,iDAAiD;;IAEjD,iDAAiD;;CAEzC,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,aAAa,EAAE,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0BAA0B;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,UAAU,EAAE,IAAI,CAAC;IACjB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAElD;;;;;;OAMG;IACG,WAAW,CACf,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,cAAc,CAAC;IAsE1B;;;;;;OAMG;IACH,mBAAmB,CAAC,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa,GAAG,SAAS;IAiDlF;;;;;OAKG;IACH,0BAA0B,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM;IAY1D;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA6B/B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAehC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAe1B;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,YAAY,GACpB,yBAAyB,CAE3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,aAAa,EACtB,gBAAgB,GAAE,MAAiD,EACnE,gBAAgB,SAAI,EACpB,WAAW,SAAI,GACd,SAAS,CAmCX"}

package/dist/types/query/zpd.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Zone of Proximal Development (ZPD) Calculator
+ *
+ * Implements Vygotsky's Zone of Proximal Development theory to identify
+ * skills that are "just right" for a learner - challenging but achievable.
+ *
+ * @packageDocumentation
+ */
+import type { SkillNode, SkillId } from '../types/skill.js';
+import type { MasteryState } from '../types/mastery.js';
+import type { GraphStorage } from '../types/storage.js';
+import type { ZPDResult, ZPDOptions } from '../types/query.js';
+/**
+ * Default options for ZPD calculation
+ */
+export declare const ZPD_DEFAULTS: Required<Omit<ZPDOptions, 'filterTags' | 'filterDomain'>>;
+/**
+ * Learner profile for ZPD calculation
+ */
+export interface LearnerProfile {
+    /** Mastery states for skills (keyed by skill ID) */
+    masteryStates: Map<SkillId, MasteryState>;
+    /** Estimated learner ability level (0-1, derived from average mastery) */
+    abilityLevel?: number;
+}
+/**
+ * ZPD Calculator
+ *
+ * Calculates the Zone of Proximal Development for a learner based on:
+ * 1. Current mastery states
+ * 2. Prerequisite graph structure
+ * 3. Skill difficulty levels
+ *
+ * A skill is in the ZPD if:
+ * - All prerequisites are mastered
+ * - The skill is not yet mastered
+ * - The skill difficulty is within tolerance of learner ability
+ */
+export declare class ZPDCalculator {
+    private readonly storage;
+    constructor(storage: GraphStorage);
+    /**
+     * Calculate ZPD for a learner
+     *
+     * @param learner - Learner profile with mastery states
+     * @param options - Calculation options
+     * @returns ZPD result with ready skills and blocked skills
+     *
+     * @example
+     * ```typescript
+     * const calculator = new ZPDCalculator(storage);
+     *
+     * const learner = {
+     *   masteryStates: new Map([
+     *     ['skill-1', { skillId: 'skill-1', mastery: 0.9, ... }],
+     *     ['skill-2', { skillId: 'skill-2', mastery: 0.3, ... }],
+     *   ])
+     * };
+     *
+     * const zpd = await calculator.calculate(learner);
+     * console.log('Ready to learn:', zpd.ready.map(s => s.name));
+     * ```
+     */
+    calculate(learner: LearnerProfile, options?: ZPDOptions): Promise<ZPDResult>;
+    /**
+     * Get the next recommended skill to learn
+     *
+     * @param learner - Learner profile
+     * @param options - ZPD options
+     * @returns The highest priority skill to learn next, or null if none available
+     */
+    getNextSkill(learner: LearnerProfile, options?: ZPDOptions): Promise<SkillNode | null>;
+    /**
+     * Check if a specific skill is in the learner's ZPD
+     *
+     * @param skillId - Skill to check
+     * @param learner - Learner profile
+     * @returns Object with inZPD status and blocking prerequisites if any
+     */
+    isInZPD(skillId: SkillId, learner: LearnerProfile): Promise<{
+        inZPD: boolean;
+        blocking: string[];
+    }>;
+    /**
+     * Calculate learner ability level from mastery states
+     */
+    private calculateAbilityLevel;
+    /**
+     * Sort skills by learning priority
+     */
+    private sortByPriority;
+}
+/**
+ * Create a ZPD calculator
+ */
+export declare function createZPDCalculator(storage: GraphStorage): ZPDCalculator;
+//# sourceMappingURL=zpd.d.ts.map

package/dist/types/query/zpd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zpd.d.ts","sourceRoot":"","sources":["../../../src/query/zpd.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,GAAG,cAAc,CAAC,CAIlF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,aAAa,EAAE,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAE1C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAElD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IAsFtF;;;;;;OAMG;IACG,YAAY,CAChB,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAK5B;;;;;;OAMG;IACG,OAAO,CACX,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA+BlD;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACH,OAAO,CAAC,cAAc;CAiBvB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAExE"}