learngraph 0.4.0 → 0.5.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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learngraph",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The world's first AI-powered learning path generator. Transform syllabi into personalized mastery paths with Zone of Proximal Development (ZPD), Bloom's Taxonomy, spaced repetition, and Bayesian Knowledge Tracing built in. Every student's path to mastery.",
   "author": "Dr. Ernesto Lee <dr.ernesto.lee@gmail.com>",
   "license": "Apache-2.0",