@shaxpir/duiduidui-models 1.9.22 → 1.9.25

package/dist/models/SkillLevel.d.ts

@@ -15,31 +15,71 @@ export interface SkillLevel {
     sigma: number;
 }
 /**
- * Legacy interface for backwards compatibility during migration.
- * Maps to the new SkillLevel interface.
- * @deprecated Use SkillLevel with mu/sigma instead
+ * Parameters for skill level updates.
+ * All parameters are optional and have sensible defaults.
  */
-export interface LegacySkillLevel {
-    rating: number;
-    rating_deviation: number;
-    volatility: number;
+export interface SkillUpdateParams {
+    /**
+     * Coefficient controlling how quickly skill moves toward evidence.
+     *
+     * When informative evidence is received, skill moves this fraction
+     * of the distance from current mu toward the card's difficulty.
+     *
+     * - 0.5 means move halfway toward the card difficulty each time
+     * - Lower values = more conservative, requires more evidence
+     * - Higher values = more aggressive, trusts individual observations more
+     *
+     * With coefficient 0.5, approaching a difficulty level:
+     * - After 1 review: 50% of the way
+     * - After 2 reviews: 75% of the way
+     * - After 3 reviews: 87.5% of the way
+     * - After 5 reviews: 96.9% of the way
+     *
+     * @default 0.5
+     */
+    updateCoefficient?: number;
+    /**
+     * Coefficient for sigma updates when evidence is informative.
+     * Sigma is multiplied by this value (so 0.9 = 10% decay).
+     *
+     * @default 0.9
+     */
+    sigmaDecay?: number;
+    /**
+     * Minimum sigma value to prevent over-confidence.
+     * Even with many observations, we maintain some uncertainty.
+     *
+     * @default 5
+     */
+    minSigma?: number;
+    /**
+     * Maximum sigma value.
+     *
+     * @default 100
+     */
+    maxSigma?: number;
 }
 /**
- * Model for updating and managing skill levels using Item Response Theory (IRT).
+ * Default parameters for skill updates.
+ */
+export declare const DEFAULT_SKILL_PARAMS: Required<SkillUpdateParams>;
+/**
+ * Model for updating and managing skill levels using Item Response Theory (IRT)
+ * with asymmetric evidence clamping.
  *
- * This model estimates user skill based on a logistic psychometric function:
- *   P(success | difficulty d, skill μ) = 1 / (1 + exp(k * (d - μ)))
+ * This model is based on standard IRT psychometric principles but applies a
+ * clamping constraint that reflects the asymmetric nature of flashcard evidence:
  *
- * Where:
- * - μ (mu) is the skill level we're estimating
- * - k controls the steepness of the transition from "easy" to "hard"
- * - Cards with difficulty < μ are likely to be answered correctly
- * - Cards with difficulty > μ are likely to be answered incorrectly
+ * - Succeeding on a card of difficulty D provides evidence that skill >= D,
+ *   but a single success should NOT push skill estimate above D
+ * - Failing on a card of difficulty D provides evidence that skill <= D,
+ *   but a single failure should NOT push skill estimate below D
+ * - Succeeding on easy cards (difficulty < skill) is uninformative
+ * - Failing on hard cards (difficulty > skill) is uninformative
  *
- * The model uses Bayesian updating with a Gaussian approximation:
- * - Each observation updates μ based on prediction error
- * - Uncertainty (σ) decreases as we accumulate evidence
- * - No full history is needed - just μ and σ are sufficient statistics
+ * The update rule moves skill toward the card difficulty by a fraction (coefficient),
+ * ensuring that skill can only asymptotically approach demonstrated competence
+ * through multiple consistent observations.
  *
  * Scale semantics:
  * - μ = 0: absolute beginner (knows ~0 characters)
@@ -48,48 +88,31 @@ export interface LegacySkillLevel {
  */
 export declare class SkillLevelModel {
     /**
-     * Steepness parameter for the logistic function.
-     *
-     * Controls how sharply success probability drops as difficulty exceeds skill:
-     * - k = 0.05 means the transition zone spans ~40 difficulty points
-     * - At difficulty = μ, P(success) = 50%
-     * - At difficulty = μ + 20, P(success) ≈ 27%
-     * - At difficulty = μ + 40, P(success) ≈ 12%
-     *
-     * Lower k = more gradual transition, higher k = sharper cutoff.
+     * Discrimination parameter for predictSuccess logistic function.
+     * Controls how sharply probability transitions around difficulty = mu.
+     * Higher values = steeper curve. 0.05 gives gradual transition over ~60 difficulty units.
      */
     private static readonly K;
     /**
-     * Minimum sigma value to prevent over-confidence.
-     * Even with many observations, we maintain some uncertainty.
-     */
-    private static readonly MIN_SIGMA;
-    /**
-     * Maximum sigma value for initial state.
-     */
-    private static readonly MAX_SIGMA;
-    /**
-     * Update skill level using IRT after a review.
+     * Update skill level using clamped IRT after a review.
      *
-     * Uses Bayesian updating with a Gaussian approximation to the posterior.
-     * The update is incremental - only requires current μ and σ, not full history.
+     * Applies asymmetric evidence rules:
+     * - Success on harder card (difficulty > mu): informative, move mu up toward difficulty
+     * - Failure on easier card (difficulty < mu): informative, move mu down toward difficulty
+     * - Success on easier card: uninformative, no change
+     * - Failure on harder card: uninformative, no change
+     *
+     * When evidence is informative, sigma also decreases to reflect increased confidence.
+     * When evidence is uninformative, both mu and sigma remain unchanged.
      *
      * @param mu Current skill level estimate
      * @param sigma Current uncertainty (standard deviation)
      * @param cardDifficulty Difficulty of the card reviewed
      * @param outcome Review result (FAIL/HARD/GOOD/EASY)
+     * @param params Optional parameters to customize update behavior
      * @returns Updated skill level with new mu and sigma
      */
-    static update(mu: number, sigma: number, cardDifficulty: number, outcome: ReviewResult): SkillLevel;
-    /**
-     * Update skill level using IRT (Glicko-2 compatible signature).
-     *
-     * This method provides backwards compatibility with the old Glicko-2 API.
-     * The volatility and cardRatingDeviation parameters are ignored.
-     *
-     * @deprecated Use update() instead for cleaner IRT semantics
-     */
-    static updateWithGlicko2(rating: number, ratingDeviation: number, _volatility: number, cardDifficulty: number, _cardRatingDeviation: number, outcome: ReviewResult, _tau?: number): LegacySkillLevel;
+    static update(mu: number, sigma: number, cardDifficulty: number, outcome: ReviewResult, params?: SkillUpdateParams): SkillLevel;
     /**
      * Map a review outcome to a success score for IRT.
      *
@@ -122,19 +145,6 @@ export declare class SkillLevelModel {
      * @returns New SkillLevel object
      */
     static createDefault(initialSigma?: number): SkillLevel;
-    /**
-     * Create a default skill level in legacy format.
-     * @deprecated Use createDefault() instead
-     */
-    static createDefaultLegacy(initialRatingDeviation?: number, initialVolatility?: number): LegacySkillLevel;
-    /**
-     * Convert from legacy Glicko-2 format to IRT format.
-     */
-    static fromLegacy(legacy: LegacySkillLevel): SkillLevel;
-    /**
-     * Convert from IRT format to legacy Glicko-2 format.
-     */
-    static toLegacy(skill: SkillLevel): LegacySkillLevel;
     /**
      * Check if the skill level has high confidence (low uncertainty).
      *

package/dist/models/SkillLevel.js

@@ -1,22 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SkillLevelModel = void 0;
+exports.SkillLevelModel = exports.DEFAULT_SKILL_PARAMS = void 0;
 /**
- * Model for updating and managing skill levels using Item Response Theory (IRT).
+ * Default parameters for skill updates.
+ */
+exports.DEFAULT_SKILL_PARAMS = {
+    updateCoefficient: 0.5,
+    sigmaDecay: 0.9,
+    minSigma: 5,
+    maxSigma: 100
+};
+/**
+ * Model for updating and managing skill levels using Item Response Theory (IRT)
+ * with asymmetric evidence clamping.
  *
- * This model estimates user skill based on a logistic psychometric function:
- *   P(success | difficulty d, skill μ) = 1 / (1 + exp(k * (d - μ)))
+ * This model is based on standard IRT psychometric principles but applies a
+ * clamping constraint that reflects the asymmetric nature of flashcard evidence:
  *
- * Where:
- * - μ (mu) is the skill level we're estimating
- * - k controls the steepness of the transition from "easy" to "hard"
- * - Cards with difficulty < μ are likely to be answered correctly
- * - Cards with difficulty > μ are likely to be answered incorrectly
+ * - Succeeding on a card of difficulty D provides evidence that skill >= D,
+ *   but a single success should NOT push skill estimate above D
+ * - Failing on a card of difficulty D provides evidence that skill <= D,
+ *   but a single failure should NOT push skill estimate below D
+ * - Succeeding on easy cards (difficulty < skill) is uninformative
+ * - Failing on hard cards (difficulty > skill) is uninformative
  *
- * The model uses Bayesian updating with a Gaussian approximation:
- * - Each observation updates μ based on prediction error
- * - Uncertainty (σ) decreases as we accumulate evidence
- * - No full history is needed - just μ and σ are sufficient statistics
+ * The update rule moves skill toward the card difficulty by a fraction (coefficient),
+ * ensuring that skill can only asymptotically approach demonstrated competence
+ * through multiple consistent observations.
  *
  * Scale semantics:
  * - μ = 0: absolute beginner (knows ~0 characters)
@@ -25,53 +35,42 @@ exports.SkillLevelModel = void 0;
  */
 class SkillLevelModel {
     /**
-     * Update skill level using IRT after a review.
+     * Update skill level using clamped IRT after a review.
      *
-     * Uses Bayesian updating with a Gaussian approximation to the posterior.
-     * The update is incremental - only requires current μ and σ, not full history.
+     * Applies asymmetric evidence rules:
+     * - Success on harder card (difficulty > mu): informative, move mu up toward difficulty
+     * - Failure on easier card (difficulty < mu): informative, move mu down toward difficulty
+     * - Success on easier card: uninformative, no change
+     * - Failure on harder card: uninformative, no change
+     *
+     * When evidence is informative, sigma also decreases to reflect increased confidence.
+     * When evidence is uninformative, both mu and sigma remain unchanged.
      *
      * @param mu Current skill level estimate
      * @param sigma Current uncertainty (standard deviation)
      * @param cardDifficulty Difficulty of the card reviewed
      * @param outcome Review result (FAIL/HARD/GOOD/EASY)
+     * @param params Optional parameters to customize update behavior
      * @returns Updated skill level with new mu and sigma
      */
-    static update(mu, sigma, cardDifficulty, outcome) {
-        const k = SkillLevelModel.K;
-        // Map outcome to success value (0 to 1)
-        const y = SkillLevelModel.outcomeToScore(outcome);
-        // Predicted probability of success given current skill estimate
-        const p = 1 / (1 + Math.exp(k * (cardDifficulty - mu)));
-        // Prediction error: positive if did better than expected, negative if worse
-        const error = y - p;
-        // Fisher information for logistic model (highest at p = 0.5)
-        const info = p * (1 - p);
-        // Update variance (precision increases with information)
-        const sigmaSquared = sigma * sigma;
-        const newSigmaSquared = 1 / (1 / sigmaSquared + k * k * info);
-        const newSigma = Math.sqrt(newSigmaSquared);
-        // Update mean (shift toward evidence)
-        const newMu = mu + newSigmaSquared * k * error;
-        return {
-            mu: Math.max(0, newMu), // Skill can't go negative
-            sigma: Math.max(SkillLevelModel.MIN_SIGMA, Math.min(SkillLevelModel.MAX_SIGMA, newSigma))
-        };
-    }
-    /**
-     * Update skill level using IRT (Glicko-2 compatible signature).
-     *
-     * This method provides backwards compatibility with the old Glicko-2 API.
-     * The volatility and cardRatingDeviation parameters are ignored.
-     *
-     * @deprecated Use update() instead for cleaner IRT semantics
-     */
-    static updateWithGlicko2(rating, ratingDeviation, _volatility, cardDifficulty, _cardRatingDeviation, outcome, _tau = 0.5) {
-        const result = SkillLevelModel.update(rating, ratingDeviation, cardDifficulty, outcome);
-        // Return in legacy format
+    static update(mu, sigma, cardDifficulty, outcome, params = {}) {
+        const { updateCoefficient = exports.DEFAULT_SKILL_PARAMS.updateCoefficient, sigmaDecay = exports.DEFAULT_SKILL_PARAMS.sigmaDecay, minSigma = exports.DEFAULT_SKILL_PARAMS.minSigma, maxSigma = exports.DEFAULT_SKILL_PARAMS.maxSigma } = params;
+        const isSuccess = outcome === 'EASY' || outcome === 'GOOD';
+        const isFailure = outcome === 'FAIL' || outcome === 'HARD';
+        // Determine if this observation is informative
+        const isInformative = (isSuccess && cardDifficulty > mu) || // Success on harder card
+            (isFailure && cardDifficulty < mu); // Failure on easier card
+        if (!isInformative) {
+            // Uninformative evidence: no change to skill estimate
+            return { mu, sigma };
+        }
+        // Informative evidence: move mu toward card difficulty
+        const newMu = mu + updateCoefficient * (cardDifficulty - mu);
+        // Decrease sigma since we learned something
+        const newSigma = sigma * sigmaDecay;
         return {
-            rating: result.mu,
-            rating_deviation: result.sigma,
-            volatility: 0.06 // Fixed value, not used in IRT
+            mu: Math.max(0, newMu),
+            sigma: Math.max(minSigma, Math.min(maxSigma, newSigma))
         };
     }
     /**
@@ -127,36 +126,6 @@ class SkillLevelModel {
             sigma: initialSigma
         };
     }
-    /**
-     * Create a default skill level in legacy format.
-     * @deprecated Use createDefault() instead
-     */
-    static createDefaultLegacy(initialRatingDeviation = 50, initialVolatility = 0.06) {
-        return {
-            rating: 0,
-            rating_deviation: initialRatingDeviation,
-            volatility: initialVolatility
-        };
-    }
-    /**
-     * Convert from legacy Glicko-2 format to IRT format.
-     */
-    static fromLegacy(legacy) {
-        return {
-            mu: legacy.rating,
-            sigma: legacy.rating_deviation
-        };
-    }
-    /**
-     * Convert from IRT format to legacy Glicko-2 format.
-     */
-    static toLegacy(skill) {
-        return {
-            rating: skill.mu,
-            rating_deviation: skill.sigma,
-            volatility: 0.06
-        };
-    }
     /**
      * Check if the skill level has high confidence (low uncertainty).
      *
@@ -170,23 +139,8 @@ class SkillLevelModel {
 }
 exports.SkillLevelModel = SkillLevelModel;
 /**
- * Steepness parameter for the logistic function.
- *
- * Controls how sharply success probability drops as difficulty exceeds skill:
- * - k = 0.05 means the transition zone spans ~40 difficulty points
- * - At difficulty = μ, P(success) = 50%
- * - At difficulty = μ + 20, P(success) ≈ 27%
- * - At difficulty = μ + 40, P(success) ≈ 12%
- *
- * Lower k = more gradual transition, higher k = sharper cutoff.
+ * Discrimination parameter for predictSuccess logistic function.
+ * Controls how sharply probability transitions around difficulty = mu.
+ * Higher values = steeper curve. 0.05 gives gradual transition over ~60 difficulty units.
  */
 SkillLevelModel.K = 0.05;
-/**
- * Minimum sigma value to prevent over-confidence.
- * Even with many observations, we maintain some uncertainty.
- */
-SkillLevelModel.MIN_SIGMA = 5;
-/**
- * Maximum sigma value for initial state.
- */
-SkillLevelModel.MAX_SIGMA = 100;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaxpir/duiduidui-models",
-  "version": "1.9.22",
+  "version": "1.9.25",
   "repository": {
     "type": "git",
     "url": "https://github.com/shaxpir/duiduidui-models"