learngraph 0.3.0 → 0.5.0

package/dist/cjs/query/spaced-repetition.js

@@ -0,0 +1,298 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpacedRepetitionScheduler = exports.SM2_CONSTANTS = exports.REVIEW_DEFAULTS = void 0;
+exports.createSpacedRepetitionScheduler = createSpacedRepetitionScheduler;
+exports.calculateSM2 = calculateSM2;
+/**
+ * Default options for review scheduling
+ */
+exports.REVIEW_DEFAULTS = {
+    includeUpcoming: true,
+    upcomingDays: 7,
+    maxReviews: 50,
+};
+/**
+ * SM-2 algorithm constants
+ */
+exports.SM2_CONSTANTS = {
+    /** Minimum easiness factor */
+    MIN_EASINESS: 1.3,
+    /** Default easiness factor */
+    DEFAULT_EASINESS: 2.5,
+    /** Maximum easiness factor */
+    MAX_EASINESS: 3.5,
+    /** Initial interval (days) after first review */
+    INITIAL_INTERVAL: 1,
+    /** Second interval (days) after second review */
+    SECOND_INTERVAL: 6,
+};
+/**
+ * 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`);
+ * ```
+ */
+class SpacedRepetitionScheduler {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Get the review schedule for a learner
+     *
+     * @param learner - Current learner state
+     * @param options - Schedule options
+     * @returns Review schedule with due and upcoming items
+     */
+    async getSchedule(learner, options = {}) {
+        const opts = { ...exports.REVIEW_DEFAULTS, ...options };
+        const now = new Date();
+        const upcomingCutoff = new Date(now.getTime() + opts.upcomingDays * 24 * 60 * 60 * 1000);
+        // Get all skills that have been practiced
+        const allSkills = await this.storage.findSkills({});
+        const dueNow = [];
+        const upcoming = [];
+        for (const skill of allSkills) {
+            const mastery = learner.masteryStates.get(skill.id);
+            if (!mastery) {
+                continue; // Never practiced
+            }
+            // Only schedule reviews for skills with some mastery
+            if (mastery.mastery < 0.1) {
+                continue;
+            }
+            const nextReview = this.calculateNextReviewDate(mastery);
+            const priority = this.calculatePriority(mastery, nextReview, now);
+            const reviewItem = {
+                skill,
+                state: {
+                    mastery: mastery.mastery,
+                    lastAttempt: mastery.lastAttempt,
+                    streak: mastery.streak,
+                },
+                nextReview,
+                priority,
+            };
+            if (nextReview <= now) {
+                dueNow.push(reviewItem);
+            }
+            else if (opts.includeUpcoming && nextReview <= upcomingCutoff) {
+                upcoming.push(reviewItem);
+            }
+        }
+        // Sort by priority (highest first)
+        dueNow.sort((a, b) => b.priority - a.priority);
+        upcoming.sort((a, b) => a.nextReview.getTime() - b.nextReview.getTime());
+        // Apply limits
+        const limitedDue = opts.maxReviews ? dueNow.slice(0, opts.maxReviews) : dueNow;
+        const remainingLimit = opts.maxReviews
+            ? Math.max(0, opts.maxReviews - limitedDue.length)
+            : undefined;
+        const limitedUpcoming = remainingLimit !== undefined
+            ? upcoming.slice(0, remainingLimit)
+            : upcoming;
+        // Calculate total review time
+        const totalReviewMinutes = [...limitedDue, ...limitedUpcoming].reduce((sum, item) => sum + Math.ceil(item.skill.estimatedMinutes * 0.3), // Reviews are ~30% of initial learning time
+        0);
+        return {
+            dueNow: limitedDue,
+            upcoming: limitedUpcoming,
+            totalReviewMinutes,
+        };
+    }
+    /**
+     * 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, quality) {
+        const now = new Date();
+        // Get current SM-2 state
+        let easiness = currentState.easinessFactor ?? exports.SM2_CONSTANTS.DEFAULT_EASINESS;
+        let repetitions = currentState.streak;
+        let interval;
+        // Quality must be >= 3 for successful recall
+        if (quality >= 3) {
+            // Successful recall
+            if (repetitions === 0) {
+                interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+            }
+            else if (repetitions === 1) {
+                interval = exports.SM2_CONSTANTS.SECOND_INTERVAL;
+            }
+            else {
+                // Get previous interval from last attempt
+                const lastInterval = this.estimatePreviousInterval(currentState);
+                interval = Math.round(lastInterval * easiness);
+            }
+            repetitions++;
+        }
+        else {
+            // Failed recall - reset to beginning
+            repetitions = 0;
+            interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        }
+        // Update easiness factor
+        // EF = EF + (0.1 - (5 - q) * (0.08 + (5 - q) * 0.02))
+        const easinessChange = 0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02);
+        easiness = Math.max(exports.SM2_CONSTANTS.MIN_EASINESS, Math.min(exports.SM2_CONSTANTS.MAX_EASINESS, easiness + easinessChange));
+        // Calculate next review date
+        const nextReview = new Date(now.getTime() + interval * 24 * 60 * 60 * 1000);
+        return {
+            easinessFactor: easiness,
+            intervalDays: interval,
+            nextReview,
+            repetitions,
+        };
+    }
+    /**
+     * Convert review quality to mastery update
+     *
+     * @param quality - Review quality (0-5)
+     * @returns Mastery level adjustment
+     */
+    qualityToMasteryAdjustment(quality) {
+        // Map quality to mastery change
+        switch (quality) {
+            case 5: return 0.1; // Perfect - increase mastery
+            case 4: return 0.05; // Correct with hesitation
+            case 3: return 0.0; // Correct with difficulty - maintain
+            case 2: return -0.1; // Incorrect but close
+            case 1: return -0.2; // Poor recall
+            case 0: return -0.3; // Complete failure
+        }
+    }
+    /**
+     * Calculate next review date based on current mastery state
+     */
+    calculateNextReviewDate(mastery) {
+        if (!mastery.lastAttempt) {
+            return new Date(); // Due immediately
+        }
+        const easiness = mastery.easinessFactor ?? exports.SM2_CONSTANTS.DEFAULT_EASINESS;
+        const streak = mastery.streak;
+        // Calculate interval based on streak
+        let interval;
+        if (streak === 0) {
+            interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        }
+        else if (streak === 1) {
+            interval = exports.SM2_CONSTANTS.SECOND_INTERVAL;
+        }
+        else {
+            // Exponential growth based on streak and easiness
+            interval = Math.round(exports.SM2_CONSTANTS.SECOND_INTERVAL * Math.pow(easiness, streak - 1));
+        }
+        // Clamp to reasonable bounds (1 day to 1 year)
+        interval = Math.max(1, Math.min(365, interval));
+        return new Date(mastery.lastAttempt.getTime() + interval * 24 * 60 * 60 * 1000);
+    }
+    /**
+     * Estimate previous interval from mastery state
+     */
+    estimatePreviousInterval(mastery) {
+        const streak = mastery.streak;
+        const easiness = mastery.easinessFactor ?? exports.SM2_CONSTANTS.DEFAULT_EASINESS;
+        if (streak <= 1) {
+            return exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        }
+        else if (streak === 2) {
+            return exports.SM2_CONSTANTS.SECOND_INTERVAL;
+        }
+        else {
+            return Math.round(exports.SM2_CONSTANTS.SECOND_INTERVAL * Math.pow(easiness, streak - 2));
+        }
+    }
+    /**
+     * Calculate review priority
+     * Higher priority = more urgent to review
+     */
+    calculatePriority(mastery, nextReview, now) {
+        // Base priority on how overdue the review is
+        const overdueDays = (now.getTime() - nextReview.getTime()) / (24 * 60 * 60 * 1000);
+        // Higher mastery items get slightly lower priority (we want to maintain them)
+        const masteryFactor = 1 - mastery.mastery * 0.3;
+        // Combine factors
+        // Overdue items get positive priority, upcoming items get negative
+        return overdueDays * masteryFactor * 10;
+    }
+}
+exports.SpacedRepetitionScheduler = SpacedRepetitionScheduler;
+/**
+ * Create a spaced repetition scheduler
+ */
+function createSpacedRepetitionScheduler(storage) {
+    return new SpacedRepetitionScheduler(storage);
+}
+/**
+ * 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
+ */
+function calculateSM2(quality, previousEasiness = exports.SM2_CONSTANTS.DEFAULT_EASINESS, previousInterval = 0, repetitions = 0) {
+    const now = new Date();
+    let easiness = previousEasiness;
+    let interval;
+    let newRepetitions = repetitions;
+    if (quality >= 3) {
+        // Successful recall
+        if (newRepetitions === 0) {
+            interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        }
+        else if (newRepetitions === 1) {
+            interval = exports.SM2_CONSTANTS.SECOND_INTERVAL;
+        }
+        else {
+            interval = Math.round(previousInterval * easiness);
+        }
+        newRepetitions++;
+    }
+    else {
+        // Failed - reset
+        interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        newRepetitions = 0;
+    }
+    // Update easiness
+    const easinessChange = 0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02);
+    easiness = Math.max(exports.SM2_CONSTANTS.MIN_EASINESS, Math.min(exports.SM2_CONSTANTS.MAX_EASINESS, easiness + easinessChange));
+    return {
+        easinessFactor: easiness,
+        intervalDays: interval,
+        nextReview: new Date(now.getTime() + interval * 24 * 60 * 60 * 1000),
+        repetitions: newRepetitions,
+    };
+}
+//# sourceMappingURL=spaced-repetition.js.map

package/dist/cjs/query/spaced-repetition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaced-repetition.js","sourceRoot":"","sources":["../../../src/query/spaced-repetition.ts"],"names":[],"mappings":"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"}

package/dist/cjs/query/zpd.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZPDCalculator = exports.ZPD_DEFAULTS = void 0;
+exports.createZPDCalculator = createZPDCalculator;
+/**
+ * Default options for ZPD calculation
+ */
+exports.ZPD_DEFAULTS = {
+    difficultyTolerance: 0.2,
+    prioritizeThresholdConcepts: true,
+    maxResults: 50,
+};
+/**
+ * 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
+ */
+class ZPDCalculator {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * 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));
+     * ```
+     */
+    async calculate(learner, options = {}) {
+        const opts = { ...exports.ZPD_DEFAULTS, ...options };
+        // Get all skills from storage
+        let allSkills = await this.storage.findSkills({});
+        // Apply filters
+        if (opts.filterTags && opts.filterTags.length > 0) {
+            allSkills = allSkills.filter((skill) => opts.filterTags.some((tag) => skill.tags.includes(tag)));
+        }
+        if (opts.filterDomain) {
+            allSkills = allSkills.filter((skill) => skill.metadata?.domain === opts.filterDomain);
+        }
+        // Calculate learner ability level if not provided
+        const abilityLevel = learner.abilityLevel ?? this.calculateAbilityLevel(learner);
+        // Categorize skills
+        const zpd = [];
+        const ready = [];
+        const blocked = new Map();
+        let masteredCount = 0;
+        for (const skill of allSkills) {
+            const mastery = learner.masteryStates.get(skill.id);
+            const masteryLevel = mastery?.mastery ?? 0;
+            // Check if already mastered
+            if (masteryLevel >= skill.masteryThreshold) {
+                masteredCount++;
+                continue;
+            }
+            // Get prerequisites
+            const prerequisites = await this.storage.getPrerequisitesOf(skill.id);
+            const unmetPrereqs = [];
+            for (const prereq of prerequisites) {
+                const prereqMastery = learner.masteryStates.get(prereq.id);
+                const prereqLevel = prereqMastery?.mastery ?? 0;
+                if (prereqLevel < prereq.masteryThreshold) {
+                    unmetPrereqs.push(prereq.name);
+                }
+            }
+            if (unmetPrereqs.length > 0) {
+                // Skill is blocked
+                blocked.set(skill.id, unmetPrereqs);
+            }
+            else {
+                // Skill is in ZPD (prerequisites met, not yet mastered)
+                zpd.push(skill);
+                // Check if within difficulty tolerance
+                const difficultyDelta = skill.difficulty - abilityLevel;
+                if (difficultyDelta <= opts.difficultyTolerance) {
+                    ready.push(skill);
+                }
+            }
+        }
+        // Sort ready skills by priority
+        this.sortByPriority(ready, opts.prioritizeThresholdConcepts);
+        // Limit results
+        const limitedReady = opts.maxResults ? ready.slice(0, opts.maxResults) : ready;
+        const limitedZpd = opts.maxResults ? zpd.slice(0, opts.maxResults) : zpd;
+        return {
+            zpd: limitedZpd,
+            ready: limitedReady,
+            blocked,
+            stats: {
+                totalSkills: allSkills.length,
+                mastered: masteredCount,
+                inZPD: zpd.length,
+                blocked: blocked.size,
+            },
+        };
+    }
+    /**
+     * 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
+     */
+    async getNextSkill(learner, options = {}) {
+        const zpd = await this.calculate(learner, { ...options, maxResults: 1 });
+        return zpd.ready[0] ?? zpd.zpd[0] ?? 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
+     */
+    async isInZPD(skillId, learner) {
+        const skill = await this.storage.getSkill(skillId);
+        if (!skill) {
+            return { inZPD: false, blocking: ['Skill not found'] };
+        }
+        // Check if already mastered
+        const mastery = learner.masteryStates.get(skillId);
+        if (mastery && mastery.mastery >= skill.masteryThreshold) {
+            return { inZPD: false, blocking: [] };
+        }
+        // Check prerequisites
+        const prerequisites = await this.storage.getPrerequisitesOf(skillId);
+        const blocking = [];
+        for (const prereq of prerequisites) {
+            const prereqMastery = learner.masteryStates.get(prereq.id);
+            const prereqLevel = prereqMastery?.mastery ?? 0;
+            if (prereqLevel < prereq.masteryThreshold) {
+                blocking.push(prereq.name);
+            }
+        }
+        return {
+            inZPD: blocking.length === 0,
+            blocking,
+        };
+    }
+    /**
+     * Calculate learner ability level from mastery states
+     */
+    calculateAbilityLevel(learner) {
+        if (learner.masteryStates.size === 0) {
+            return 0.3; // Default starting ability
+        }
+        let totalWeighted = 0;
+        let totalWeight = 0;
+        for (const state of learner.masteryStates.values()) {
+            // Weight by mastery level (higher mastery = more confident estimate)
+            const weight = state.mastery;
+            totalWeighted += state.mastery * weight;
+            totalWeight += weight;
+        }
+        return totalWeight > 0 ? totalWeighted / totalWeight : 0.3;
+    }
+    /**
+     * Sort skills by learning priority
+     */
+    sortByPriority(skills, prioritizeThreshold) {
+        skills.sort((a, b) => {
+            // Threshold concepts first (if enabled)
+            if (prioritizeThreshold) {
+                if (a.isThresholdConcept && !b.isThresholdConcept)
+                    return -1;
+                if (!a.isThresholdConcept && b.isThresholdConcept)
+                    return 1;
+            }
+            // Then by difficulty (easier first for progressive learning)
+            if (a.difficulty !== b.difficulty) {
+                return a.difficulty - b.difficulty;
+            }
+            // Finally by estimated time (shorter first)
+            return a.estimatedMinutes - b.estimatedMinutes;
+        });
+    }
+}
+exports.ZPDCalculator = ZPDCalculator;
+/**
+ * Create a ZPD calculator
+ */
+function createZPDCalculator(storage) {
+    return new ZPDCalculator(storage);
+}
+//# sourceMappingURL=zpd.js.map

package/dist/cjs/query/zpd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zpd.js","sourceRoot":"","sources":["../../../src/query/zpd.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -36,7 +36,7 @@ export * from './types/index.js';
 /**
  * Package version
  */
-export const VERSION = '0.1.1';
+export const VERSION = '0.5.0';
 /**
  * Package name
  */