@shaxpir/duiduidui-models 1.9.20 → 1.9.22

package/dist/models/Collection.d.ts

@@ -3,7 +3,7 @@ import { CompactDateTime } from "@shaxpir/shaxpir-common";
 import { ShareSync } from '../repo';
 import { Conditions } from './Condition';
 import { Content, ContentBody, ContentId, ContentMeta } from "./Content";
-import { UncertainValue } from './Progress';
+import { SkillLevel } from './SkillLevel';
 /**
  * Display metadata for a Collection, used in the UI.
  */
@@ -23,7 +23,7 @@ export interface CollectionPayload {
     collection_key: string;
     conditions: Conditions;
     display: CollectionDisplay;
-    proficiency: UncertainValue;
+    proficiency: SkillLevel;
     term_scores: {
         [termKey: string]: number;
     };
@@ -77,10 +77,9 @@ export declare class Collection extends Content {
     get description(): string;
     get icon(): string | undefined;
     get sortOrder(): number;
-    get proficiency(): UncertainValue;
-    get proficiencyRating(): number;
-    get proficiencyRatingDeviation(): number;
-    get proficiencyVolatility(): number;
+    get proficiency(): SkillLevel;
+    get proficiencyMu(): number;
+    get proficiencySigma(): number;
     get termScores(): {
         [termKey: string]: number;
     };
@@ -125,9 +124,9 @@ export declare class Collection extends Content {
         F: number;
     };
     /**
-     * Update the Glicko-2 proficiency rating.
+     * Update the IRT proficiency rating.
      */
-    setProficiency(value: UncertainValue): void;
+    setProficiency(value: SkillLevel): void;
     /**
      * Update or add a term score in the collection.
      */

package/dist/models/Collection.js

@@ -7,6 +7,7 @@ const SenseRankEncoder_1 = require("../util/SenseRankEncoder");
 const Content_1 = require("./Content");
 const ContentKind_1 = require("./ContentKind");
 const Operation_1 = require("./Operation");
+const SkillLevel_1 = require("./SkillLevel");
 class Collection extends Content_1.Content {
     /**
      * Generate a deterministic Collection ID from userId and collectionKey.
@@ -50,12 +51,8 @@ class Collection extends Content_1.Content {
                 collection_key: params.collectionKey,
                 conditions: params.conditions,
                 display: params.display,
-                // Initial Glicko-2 proficiency - high uncertainty, no data yet
-                proficiency: {
-                    rating: 0, // Start at zero (no demonstrated skill)
-                    rating_deviation: 50, // High initial uncertainty
-                    volatility: 0.06 // Moderate initial volatility
-                },
+                // Initial IRT proficiency - high uncertainty, no data yet
+                proficiency: SkillLevel_1.SkillLevelModel.createDefault(),
                 // Empty term scores map - populated as user reviews cards
                 term_scores: {},
                 // Progress starts at zero
@@ -118,17 +115,13 @@ class Collection extends Content_1.Content {
         this.checkDisposed("Collection.proficiency");
         return shaxpir_common_1.Struct.clone(this.payload.proficiency);
     }
-    get proficiencyRating() {
-        this.checkDisposed("Collection.proficiencyRating");
-        return this.payload.proficiency.rating;
+    get proficiencyMu() {
+        this.checkDisposed("Collection.proficiencyMu");
+        return this.payload.proficiency.mu;
     }
-    get proficiencyRatingDeviation() {
-        this.checkDisposed("Collection.proficiencyRatingDeviation");
-        return this.payload.proficiency.rating_deviation;
-    }
-    get proficiencyVolatility() {
-        this.checkDisposed("Collection.proficiencyVolatility");
-        return this.payload.proficiency.volatility;
+    get proficiencySigma() {
+        this.checkDisposed("Collection.proficiencySigma");
+        return this.payload.proficiency.sigma;
     }
     // ============================================================
     // Term scores getters
@@ -232,15 +225,14 @@ class Collection extends Content_1.Content {
     // Mutators
     // ============================================================
     /**
-     * Update the Glicko-2 proficiency rating.
+     * Update the IRT proficiency rating.
      */
     setProficiency(value) {
         this.checkDisposed("Collection.setProficiency");
         if (!shaxpir_common_1.Struct.equals(this.payload.proficiency, value)) {
             const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'proficiency', 'rating'], value.rating);
-            batch.setPathValue(['payload', 'proficiency', 'rating_deviation'], value.rating_deviation);
-            batch.setPathValue(['payload', 'proficiency', 'volatility'], value.volatility);
+            batch.setPathValue(['payload', 'proficiency', 'mu'], value.mu);
+            batch.setPathValue(['payload', 'proficiency', 'sigma'], value.sigma);
             batch.commit();
         }
     }

package/dist/models/Progress.d.ts

@@ -2,11 +2,7 @@ import { Doc } from '@shaxpir/sharedb/lib/client';
 import { CompactDate } from "@shaxpir/shaxpir-common";
 import { ShareSync } from '../repo';
 import { Content, ContentBody, ContentId, ContentMeta } from "./Content";
-export interface UncertainValue {
-    rating: number;
-    rating_deviation: number;
-    volatility: number;
-}
+import { SkillLevel } from './SkillLevel';
 export interface StreakData {
     daily: {
         current: number;
@@ -26,7 +22,7 @@ export interface StreakData {
     total_days: number;
 }
 export interface ProgressPayload {
-    skill_level: UncertainValue;
+    skill_level: SkillLevel;
     cognitive_load: number;
     streaks?: StreakData;
     total_review_count: number;
@@ -40,18 +36,16 @@ export declare class Progress extends Content {
     static create(userId: ContentId): Progress;
     constructor(doc: Doc, shouldAcquire: boolean, shareSync: ShareSync);
     get payload(): ProgressPayload;
-    getSkillLevel(): UncertainValue;
-    getSkillLevelValue(): number;
-    getSkillLevelRatingDeviation(): number;
-    getSkillLevelVolatility(): number;
+    getSkillLevel(): SkillLevel;
+    getSkillLevelMu(): number;
+    getSkillLevelSigma(): number;
     getSkillLevelLowerBound(): number;
     getSkillLevelUpperBound(): number;
     needsCalibration(): boolean;
     getCognitiveLoad(): number;
-    setSkillLevel(uncertainValue: UncertainValue): void;
-    setSkillLevelValue(value: number): void;
-    setSkillLevelRatingDeviation(ratingDeviation: number): void;
-    setSkillLevelVolatility(volatility: number): void;
+    setSkillLevel(skillLevel: SkillLevel): void;
+    setSkillLevelMu(mu: number): void;
+    setSkillLevelSigma(sigma: number): void;
     setCognitiveLoad(value: number): void;
     getStreaks(): StreakData | undefined;
     setStreaks(streaks: StreakData): void;

package/dist/models/Progress.js

@@ -6,6 +6,7 @@ const repo_1 = require("../repo");
 const Content_1 = require("./Content");
 const ContentKind_1 = require("./ContentKind");
 const Operation_1 = require("./Operation");
+const SkillLevel_1 = require("./SkillLevel");
 class Progress extends Content_1.Content {
     static makeProgressId(userId) {
         return shaxpir_common_1.CachingHasher.makeMd5Base62Hash(userId + "-" + ContentKind_1.ContentKind.PROGRESS);
@@ -23,13 +24,9 @@ class Progress extends Content_1.Content {
                 updated_at: now
             },
             payload: {
-                skill_level: {
-                    rating: 0, // Start at absolute beginner (knows ~0 characters)
-                    rating_deviation: 50, // Initial uncertainty (±100 chars at 95% CI)
-                    volatility: 0.06 // Moderate initial volatility
-                },
+                skill_level: SkillLevel_1.SkillLevelModel.createDefault(),
                 cognitive_load: 0,
-                total_review_count: 0 // Start with zero lifetime reviews
+                total_review_count: 0
             }
         });
     }
@@ -44,71 +41,56 @@ class Progress extends Content_1.Content {
         this.checkDisposed("Progress.getSkillLevel");
         return shaxpir_common_1.Struct.clone(this.payload.skill_level);
     }
-    getSkillLevelValue() {
-        this.checkDisposed("Progress.getSkillLevelValue");
-        return this.payload.skill_level.rating;
+    getSkillLevelMu() {
+        this.checkDisposed("Progress.getSkillLevelMu");
+        return this.payload.skill_level.mu;
     }
-    getSkillLevelRatingDeviation() {
-        this.checkDisposed("Progress.getSkillLevelRatingDeviation");
-        return this.payload.skill_level.rating_deviation;
-    }
-    getSkillLevelVolatility() {
-        this.checkDisposed("Progress.getSkillLevelVolatility");
-        return this.payload.skill_level.volatility;
+    getSkillLevelSigma() {
+        this.checkDisposed("Progress.getSkillLevelSigma");
+        return this.payload.skill_level.sigma;
     }
     getSkillLevelLowerBound() {
         this.checkDisposed("Progress.getSkillLevelLowerBound");
-        const { SkillLevelModel } = require('./SkillLevel');
-        const bounds = SkillLevelModel.calculateBounds(this.payload.skill_level.rating, this.payload.skill_level.rating_deviation);
+        const bounds = SkillLevel_1.SkillLevelModel.calculateBounds(this.payload.skill_level.mu, this.payload.skill_level.sigma);
         return bounds.lower;
     }
     getSkillLevelUpperBound() {
         this.checkDisposed("Progress.getSkillLevelUpperBound");
-        const { SkillLevelModel } = require('./SkillLevel');
-        const bounds = SkillLevelModel.calculateBounds(this.payload.skill_level.rating, this.payload.skill_level.rating_deviation);
+        const bounds = SkillLevel_1.SkillLevelModel.calculateBounds(this.payload.skill_level.mu, this.payload.skill_level.sigma);
         return bounds.upper;
     }
     needsCalibration() {
         this.checkDisposed("Progress.needsCalibration");
-        // High rating deviation means we need more data to calibrate user level
-        // rating_deviation > 30 means confidence bounds are still quite wide (±60 chars at 95% CI)
-        return this.payload.skill_level.rating_deviation > 30;
+        // High sigma means we need more data to calibrate user level
+        // sigma > 30 means confidence bounds are still quite wide (±60 chars at 95% CI)
+        return this.payload.skill_level.sigma > 30;
     }
     getCognitiveLoad() {
         this.checkDisposed("Progress.getCognitiveLoad");
         return this.payload.cognitive_load;
     }
-    setSkillLevel(uncertainValue) {
+    setSkillLevel(skillLevel) {
         this.checkDisposed("Progress.setSkillLevel");
-        if (!shaxpir_common_1.Struct.equals(this.payload.skill_level, uncertainValue)) {
-            const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'skill_level', 'rating'], uncertainValue.rating);
-            batch.setPathValue(['payload', 'skill_level', 'rating_deviation'], uncertainValue.rating_deviation);
-            batch.setPathValue(['payload', 'skill_level', 'volatility'], uncertainValue.volatility);
-            batch.commit();
-        }
-    }
-    setSkillLevelValue(value) {
-        this.checkDisposed("Progress.setSkillLevelValue");
-        if (this.payload.skill_level.rating !== value) {
+        if (!shaxpir_common_1.Struct.equals(this.payload.skill_level, skillLevel)) {
             const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'skill_level', 'rating'], value);
+            batch.setPathValue(['payload', 'skill_level', 'mu'], skillLevel.mu);
+            batch.setPathValue(['payload', 'skill_level', 'sigma'], skillLevel.sigma);
             batch.commit();
         }
     }
-    setSkillLevelRatingDeviation(ratingDeviation) {
-        this.checkDisposed("Progress.setSkillLevelRatingDeviation");
-        if (this.payload.skill_level.rating_deviation !== ratingDeviation) {
+    setSkillLevelMu(mu) {
+        this.checkDisposed("Progress.setSkillLevelMu");
+        if (this.payload.skill_level.mu !== mu) {
             const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'skill_level', 'rating_deviation'], ratingDeviation);
+            batch.setPathValue(['payload', 'skill_level', 'mu'], mu);
             batch.commit();
         }
     }
-    setSkillLevelVolatility(volatility) {
-        this.checkDisposed("Progress.setSkillLevelVolatility");
-        if (this.payload.skill_level.volatility !== volatility) {
+    setSkillLevelSigma(sigma) {
+        this.checkDisposed("Progress.setSkillLevelSigma");
+        if (this.payload.skill_level.sigma !== sigma) {
             const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'skill_level', 'volatility'], volatility);
+            batch.setPathValue(['payload', 'skill_level', 'sigma'], sigma);
             batch.commit();
         }
     }

package/dist/models/Session.d.ts

@@ -4,7 +4,7 @@ import { ShareSync } from '../repo';
 import { Conditions } from './Condition';
 import { Content, ContentBody, ContentId, ContentMeta, ContentRef } from "./Content";
 import { Review } from './Review';
-import { UncertainValue } from './Progress';
+import { SkillLevel } from './SkillLevel';
 /**
  * How aggressively the card selection algorithm stretches the user
  * beyond their current skill level.
@@ -29,7 +29,7 @@ export interface SessionConfig {
     };
 }
 export interface SessionStats {
-    skill_level: UncertainValue;
+    skill_level: SkillLevel;
     cognitive_load: number;
     theta_distribution: {
         A: number;

package/dist/models/SkillLevel.d.ts

@@ -1,72 +1,146 @@
 import { ReviewResult } from './Review';
 import { Bounds } from './BayesianScore';
 /**
- * Represents a skill level rating with uncertainty bounds.
- * Uses the Glicko-2 rating system for skill assessment.
+ * Represents a skill level estimate with uncertainty.
+ * Uses Item Response Theory (IRT) for skill assessment.
+ *
+ * The skill level represents the estimated number of characters
+ * a user has mastered. A user with skill level N is expected to
+ * succeed on recognition tasks for characters with difficulty <= N.
  */
 export interface SkillLevel {
+    /** Estimated skill level (maps to ~number of characters mastered) */
+    mu: number;
+    /** Uncertainty in the estimate (standard deviation) */
+    sigma: number;
+}
+/**
+ * Legacy interface for backwards compatibility during migration.
+ * Maps to the new SkillLevel interface.
+ * @deprecated Use SkillLevel with mu/sigma instead
+ */
+export interface LegacySkillLevel {
     rating: number;
     rating_deviation: number;
     volatility: number;
 }
 /**
- * Model for updating and managing skill levels using the Glicko-2 rating system.
+ * Model for updating and managing skill levels using Item Response Theory (IRT).
  *
- * Unlike traditional Glicko-2 which uses a 1500-centered scale for chess,
- * this adapts the algorithm to DuiDuiDui's semantic scale where:
- * - Rating 0 = absolute beginner (knows ~0 characters)
- * - Rating 100 = knows ~100 characters
- * - Rating 3000 = knows ~3000 characters
+ * This model estimates user skill based on a logistic psychometric function:
+ *   P(success | difficulty d, skill μ) = 1 / (1 + exp(k * (d - μ)))
  *
- * The Glicko-2 algorithm is used without the typical scaling transformations,
- * working directly on our 0-10000 absolute scale.
+ * 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
+ *
+ * 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
+ *
+ * Scale semantics:
+ * - μ = 0: absolute beginner (knows ~0 characters)
+ * - μ = 100: knows ~100 characters
+ * - μ = 3000: knows ~3000 characters
  */
 export declare class SkillLevelModel {
     /**
-     * Update skill level using the Glicko-2 algorithm after a review.
+     * 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.
+     */
+    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.
      *
-     * @param rating Current skill level rating
-     * @param ratingDeviation Current rating deviation (uncertainty)
-     * @param volatility Current volatility (performance consistency)
-     * @param cardDifficulty Difficulty of the card reviewed (on same scale as rating)
-     * @param cardRatingDeviation Rating deviation for the card (typically fixed, e.g., 100)
+     * Uses Bayesian updating with a Gaussian approximation to the posterior.
+     * The update is incremental - only requires current μ and σ, not full history.
+     *
+     * @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 tau System constant controlling volatility changes (default 0.5)
-     * @returns Updated skill level with new rating, rating_deviation, and volatility
+     * @returns Updated skill level with new mu and sigma
      */
-    static updateWithGlicko2(rating: number, ratingDeviation: number, volatility: number, cardDifficulty: number, cardRatingDeviation: number, outcome: ReviewResult, tau?: number): SkillLevel;
+    static update(mu: number, sigma: number, cardDifficulty: number, outcome: ReviewResult): SkillLevel;
     /**
-     * Map a review outcome to a numeric score for Glicko-2.
+     * 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;
+    /**
+     * Map a review outcome to a success score for IRT.
      *
      * @param outcome Review result
-     * @returns Numeric score from 0.0 (complete failure) to 1.0 (perfect success)
+     * @returns Success score from 0.0 (complete failure) to 1.0 (perfect success)
      */
     static outcomeToScore(outcome: ReviewResult): number;
     /**
-     * Calculate confidence bounds from Glicko-2 parameters.
-     * Returns a proper statistical confidence interval.
+     * Calculate the probability of success on a card given skill level.
+     *
+     * @param mu Skill level estimate
+     * @param cardDifficulty Difficulty of the card
+     * @returns Probability of success (0 to 1)
+     */
+    static predictSuccess(mu: number, cardDifficulty: number): number;
+    /**
+     * Calculate confidence bounds for the skill estimate.
      *
-     * @param rating Current skill level rating
-     * @param ratingDeviation Rating deviation (standard deviation of rating)
+     * @param mu Skill level estimate
+     * @param sigma Uncertainty (standard deviation)
      * @param confidence Confidence level (0.95 for 95%, 0.99 for 99%)
      * @returns Bounds object with lower and upper confidence limits
      */
-    static calculateBounds(rating: number, ratingDeviation: number, confidence?: number): Bounds;
+    static calculateBounds(mu: number, sigma: number, confidence?: number): Bounds;
     /**
      * Create a default skill level for a new user.
-     * Starts at rating 0 (knows no characters) with high uncertainty.
+     * Starts at skill 0 (knows no characters) with high uncertainty.
      *
-     * @param initialRatingDeviation Initial rating deviation (default 50, meaning ±100 char uncertainty at 95% CI)
-     * @param initialVolatility Initial volatility (default 0.06, moderate)
+     * @param initialSigma Initial uncertainty (default 50)
      * @returns New SkillLevel object
      */
-    static createDefault(initialRatingDeviation?: number, initialVolatility?: number): SkillLevel;
+    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).
      *
-     * @param ratingDeviation Rating deviation
-     * @param threshold Maximum rating deviation to be considered "high confidence" (default 15)
-     * @returns True if uncertainty is low (rating deviation below threshold)
+     * @param sigma Uncertainty (standard deviation)
+     * @param threshold Maximum sigma to be considered "high confidence" (default 15)
+     * @returns True if uncertainty is low
      */
-    static isHighConfidence(ratingDeviation: number, threshold?: number): boolean;
+    static isHighConfidence(sigma: number, threshold?: number): boolean;
 }

package/dist/models/SkillLevel.js

@@ -1,106 +1,192 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SkillLevelModel = void 0;
-const glicko2_lite_1 = __importDefault(require("glicko2-lite"));
 /**
- * Model for updating and managing skill levels using the Glicko-2 rating system.
+ * Model for updating and managing skill levels using Item Response Theory (IRT).
  *
- * Unlike traditional Glicko-2 which uses a 1500-centered scale for chess,
- * this adapts the algorithm to DuiDuiDui's semantic scale where:
- * - Rating 0 = absolute beginner (knows ~0 characters)
- * - Rating 100 = knows ~100 characters
- * - Rating 3000 = knows ~3000 characters
+ * This model estimates user skill based on a logistic psychometric function:
+ *   P(success | difficulty d, skill μ) = 1 / (1 + exp(k * (d - μ)))
  *
- * The Glicko-2 algorithm is used without the typical scaling transformations,
- * working directly on our 0-10000 absolute scale.
+ * 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
+ *
+ * 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
+ *
+ * Scale semantics:
+ * - μ = 0: absolute beginner (knows ~0 characters)
+ * - μ = 100: knows ~100 characters
+ * - μ = 3000: knows ~3000 characters
  */
 class SkillLevelModel {
     /**
-     * Update skill level using the Glicko-2 algorithm after a review.
+     * Update skill level using 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.
      *
-     * @param rating Current skill level rating
-     * @param ratingDeviation Current rating deviation (uncertainty)
-     * @param volatility Current volatility (performance consistency)
-     * @param cardDifficulty Difficulty of the card reviewed (on same scale as rating)
-     * @param cardRatingDeviation Rating deviation for the card (typically fixed, e.g., 100)
+     * @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 tau System constant controlling volatility changes (default 0.5)
-     * @returns Updated skill level with new rating, rating_deviation, and volatility
+     * @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) {
-        // Map outcome to numeric score (0.0 to 1.0)
-        const score = SkillLevelModel.outcomeToScore(outcome);
-        // Call glicko2-lite with a single match
-        // Match format: [opponentRating, opponentRD, outcome]
-        const result = (0, glicko2_lite_1.default)(rating, ratingDeviation, volatility, [
-            [cardDifficulty, cardRatingDeviation, score]
-        ], { tau });
+    static updateWithGlicko2(rating, ratingDeviation, _volatility, cardDifficulty, _cardRatingDeviation, outcome, _tau = 0.5) {
+        const result = SkillLevelModel.update(rating, ratingDeviation, cardDifficulty, outcome);
+        // Return in legacy format
         return {
-            rating: result.rating,
-            rating_deviation: result.rd,
-            volatility: result.vol
+            rating: result.mu,
+            rating_deviation: result.sigma,
+            volatility: 0.06 // Fixed value, not used in IRT
         };
     }
     /**
-     * Map a review outcome to a numeric score for Glicko-2.
+     * Map a review outcome to a success score for IRT.
      *
      * @param outcome Review result
-     * @returns Numeric score from 0.0 (complete failure) to 1.0 (perfect success)
+     * @returns Success score from 0.0 (complete failure) to 1.0 (perfect success)
      */
     static outcomeToScore(outcome) {
         switch (outcome) {
             case 'EASY': return 1.0;
-            case 'GOOD': return 0.67;
-            case 'HARD': return 0.33;
+            case 'GOOD': return 0.85;
+            case 'HARD': return 0.3;
             case 'FAIL': return 0.0;
         }
     }
     /**
-     * Calculate confidence bounds from Glicko-2 parameters.
-     * Returns a proper statistical confidence interval.
+     * Calculate the probability of success on a card given skill level.
      *
-     * @param rating Current skill level rating
-     * @param ratingDeviation Rating deviation (standard deviation of rating)
+     * @param mu Skill level estimate
+     * @param cardDifficulty Difficulty of the card
+     * @returns Probability of success (0 to 1)
+     */
+    static predictSuccess(mu, cardDifficulty) {
+        return 1 / (1 + Math.exp(SkillLevelModel.K * (cardDifficulty - mu)));
+    }
+    /**
+     * Calculate confidence bounds for the skill estimate.
+     *
+     * @param mu Skill level estimate
+     * @param sigma Uncertainty (standard deviation)
      * @param confidence Confidence level (0.95 for 95%, 0.99 for 99%)
      * @returns Bounds object with lower and upper confidence limits
      */
-    static calculateBounds(rating, ratingDeviation, confidence = 0.95) {
+    static calculateBounds(mu, sigma, confidence = 0.95) {
         // Z-score for desired confidence level
-        // 95% CI: ±1.96 standard deviations
-        // 99% CI: ±2.58 standard deviations
         const z = confidence === 0.95 ? 1.96 : confidence === 0.99 ? 2.58 : 1.96;
         return {
-            lower: Math.max(0, rating - z * ratingDeviation),
-            upper: Math.max(0, rating + z * ratingDeviation)
+            lower: Math.max(0, mu - z * sigma),
+            upper: mu + z * sigma
         };
     }
     /**
      * Create a default skill level for a new user.
-     * Starts at rating 0 (knows no characters) with high uncertainty.
+     * Starts at skill 0 (knows no characters) with high uncertainty.
      *
-     * @param initialRatingDeviation Initial rating deviation (default 50, meaning ±100 char uncertainty at 95% CI)
-     * @param initialVolatility Initial volatility (default 0.06, moderate)
+     * @param initialSigma Initial uncertainty (default 50)
      * @returns New SkillLevel object
      */
-    static createDefault(initialRatingDeviation = 50, initialVolatility = 0.06) {
+    static createDefault(initialSigma = 50) {
+        return {
+            mu: 0,
+            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).
      *
-     * @param ratingDeviation Rating deviation
-     * @param threshold Maximum rating deviation to be considered "high confidence" (default 15)
-     * @returns True if uncertainty is low (rating deviation below threshold)
+     * @param sigma Uncertainty (standard deviation)
+     * @param threshold Maximum sigma to be considered "high confidence" (default 15)
+     * @returns True if uncertainty is low
      */
-    static isHighConfidence(ratingDeviation, threshold = 15) {
-        return ratingDeviation < threshold;
+    static isHighConfidence(sigma, threshold = 15) {
+        return sigma < threshold;
     }
 }
 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.
+ */
+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.20",
+  "version": "1.9.22",
   "repository": {
     "type": "git",
     "url": "https://github.com/shaxpir/duiduidui-models"
@@ -19,7 +19,6 @@
     "@shaxpir/duiduidui-models": "^1.4.14",
     "@shaxpir/sharedb": "^6.0.6",
     "@shaxpir/shaxpir-common": "^1.4.1",
-    "glicko2-lite": "^4.0.0",
     "ot-json1": "1.0.1",
     "ot-text-unicode": "4.0.0",
     "reconnecting-websocket": "4.4.0"