@shaxpir/duiduidui-models 1.7.5 → 1.8.0

package/dist/models/Progress.d.ts

@@ -1,12 +1,11 @@
 import { Doc } from '@shaxpir/sharedb/lib/client';
 import { CompactDate } from "@shaxpir/shaxpir-common";
 import { ShareSync } from '../repo';
-import { Bounds } from './BayesianScore';
 import { Content, ContentBody, ContentId, ContentMeta } from "./Content";
 export interface UncertainValue {
-    value: number;
-    uncertainty: number;
-    bounds: Bounds;
+    rating: number;
+    rating_deviation: number;
+    volatility: number;
 }
 export interface StreakData {
     daily: {
@@ -43,16 +42,16 @@ export declare class Progress extends Content {
     get payload(): ProgressPayload;
     getSkillLevel(): UncertainValue;
     getSkillLevelValue(): number;
-    getSkillLevelUncertainty(): number;
+    getSkillLevelRatingDeviation(): number;
+    getSkillLevelVolatility(): number;
     getSkillLevelLowerBound(): number;
     getSkillLevelUpperBound(): number;
     needsCalibration(): boolean;
     getCognitiveLoad(): number;
     setSkillLevel(uncertainValue: UncertainValue): void;
     setSkillLevelValue(value: number): void;
-    setSkillLevelUncertainty(uncertainty: number): void;
-    setSkillLevelLowerBound(lowerBound: number): void;
-    setSkillLevelUpperBound(upperBound: number): void;
+    setSkillLevelRatingDeviation(ratingDeviation: number): void;
+    setSkillLevelVolatility(volatility: number): void;
     setCognitiveLoad(value: number): void;
     getStreaks(): StreakData | undefined;
     setStreaks(streaks: StreakData): void;

package/dist/models/Progress.js

@@ -24,12 +24,9 @@ class Progress extends Content_1.Content {
             },
             payload: {
                 skill_level: {
-                    value: 0, // Start at absolute beginner
-                    uncertainty: 1000, // Maximum uncertainty
-                    bounds: {
-                        lower: 0, // Can't be worse than absolute beginner
-                        upper: 1000 // Could potentially be advanced
-                    }
+                    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
                 },
                 cognitive_load: 0,
                 total_review_count: 0 // Start with zero lifetime reviews
@@ -49,24 +46,33 @@ class Progress extends Content_1.Content {
     }
     getSkillLevelValue() {
         this.checkDisposed("Progress.getSkillLevelValue");
-        return this.payload.skill_level.value;
+        return this.payload.skill_level.rating;
     }
-    getSkillLevelUncertainty() {
-        this.checkDisposed("Progress.getSkillLevelUncertainty");
-        return this.payload.skill_level.uncertainty;
+    getSkillLevelRatingDeviation() {
+        this.checkDisposed("Progress.getSkillLevelRatingDeviation");
+        return this.payload.skill_level.rating_deviation;
+    }
+    getSkillLevelVolatility() {
+        this.checkDisposed("Progress.getSkillLevelVolatility");
+        return this.payload.skill_level.volatility;
     }
     getSkillLevelLowerBound() {
         this.checkDisposed("Progress.getSkillLevelLowerBound");
-        return this.payload.skill_level.bounds.lower;
+        const { SkillLevelModel } = require('./SkillLevel');
+        const bounds = SkillLevelModel.calculateBounds(this.payload.skill_level.rating, this.payload.skill_level.rating_deviation);
+        return bounds.lower;
     }
     getSkillLevelUpperBound() {
         this.checkDisposed("Progress.getSkillLevelUpperBound");
-        return this.payload.skill_level.bounds.upper;
+        const { SkillLevelModel } = require('./SkillLevel');
+        const bounds = SkillLevelModel.calculateBounds(this.payload.skill_level.rating, this.payload.skill_level.rating_deviation);
+        return bounds.upper;
     }
     needsCalibration() {
         this.checkDisposed("Progress.needsCalibration");
-        // High uncertainty means we need more data to calibrate user level
-        return this.payload.skill_level.uncertainty > 50;
+        // 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;
     }
     getCognitiveLoad() {
         this.checkDisposed("Progress.getCognitiveLoad");
@@ -76,42 +82,33 @@ class Progress extends Content_1.Content {
         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', 'value'], uncertainValue.value);
-            batch.setPathValue(['payload', 'skill_level', 'uncertainty'], uncertainValue.uncertainty);
-            batch.setPathValue(['payload', 'skill_level', 'bounds', 'lower'], uncertainValue.bounds.lower);
-            batch.setPathValue(['payload', 'skill_level', 'bounds', 'upper'], uncertainValue.bounds.upper);
+            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.value !== value) {
-            const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'skill_level', 'value'], value);
-            batch.commit();
-        }
-    }
-    setSkillLevelUncertainty(uncertainty) {
-        this.checkDisposed("Progress.setSkillLevelUncertainty");
-        if (this.payload.skill_level.uncertainty !== uncertainty) {
+        if (this.payload.skill_level.rating !== value) {
             const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'skill_level', 'uncertainty'], uncertainty);
+            batch.setPathValue(['payload', 'skill_level', 'rating'], value);
             batch.commit();
         }
     }
-    setSkillLevelLowerBound(lowerBound) {
-        this.checkDisposed("Progress.setSkillLevelLowerBound");
-        if (this.payload.skill_level.bounds.lower !== lowerBound) {
+    setSkillLevelRatingDeviation(ratingDeviation) {
+        this.checkDisposed("Progress.setSkillLevelRatingDeviation");
+        if (this.payload.skill_level.rating_deviation !== ratingDeviation) {
             const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'skill_level', 'bounds', 'lower'], lowerBound);
+            batch.setPathValue(['payload', 'skill_level', 'rating_deviation'], ratingDeviation);
             batch.commit();
         }
     }
-    setSkillLevelUpperBound(upperBound) {
-        this.checkDisposed("Progress.setSkillLevelUpperBound");
-        if (this.payload.skill_level.bounds.upper !== upperBound) {
+    setSkillLevelVolatility(volatility) {
+        this.checkDisposed("Progress.setSkillLevelVolatility");
+        if (this.payload.skill_level.volatility !== volatility) {
             const batch = new Operation_1.BatchOperation(this);
-            batch.setPathValue(['payload', 'skill_level', 'bounds', 'upper'], upperBound);
+            batch.setPathValue(['payload', 'skill_level', 'volatility'], volatility);
             batch.commit();
         }
     }

package/dist/models/SkillLevel.d.ts

@@ -0,0 +1,72 @@
+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.
+ */
+export interface SkillLevel {
+    rating: number;
+    rating_deviation: number;
+    volatility: number;
+}
+/**
+ * Model for updating and managing skill levels using the Glicko-2 rating system.
+ *
+ * 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
+ *
+ * The Glicko-2 algorithm is used without the typical scaling transformations,
+ * working directly on our 0-10000 absolute scale.
+ */
+export declare class SkillLevelModel {
+    /**
+     * Update skill level using the Glicko-2 algorithm 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)
+     * @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
+     */
+    static updateWithGlicko2(rating: number, ratingDeviation: number, volatility: number, cardDifficulty: number, cardRatingDeviation: number, outcome: ReviewResult, tau?: number): SkillLevel;
+    /**
+     * Map a review outcome to a numeric score for Glicko-2.
+     *
+     * @param outcome Review result
+     * @returns Numeric 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.
+     *
+     * @param rating Current skill level rating
+     * @param ratingDeviation Rating deviation (standard deviation of rating)
+     * @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;
+    /**
+     * Create a default skill level for a new user.
+     * Starts at rating 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)
+     * @returns New SkillLevel object
+     */
+    static createDefault(initialRatingDeviation?: number, initialVolatility?: number): SkillLevel;
+    /**
+     * 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)
+     */
+    static isHighConfidence(ratingDeviation: number, threshold?: number): boolean;
+}

package/dist/models/SkillLevel.js

@@ -0,0 +1,106 @@
+"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.
+ *
+ * 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
+ *
+ * The Glicko-2 algorithm is used without the typical scaling transformations,
+ * working directly on our 0-10000 absolute scale.
+ */
+class SkillLevelModel {
+    /**
+     * Update skill level using the Glicko-2 algorithm 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)
+     * @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
+     */
+    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 });
+        return {
+            rating: result.rating,
+            rating_deviation: result.rd,
+            volatility: result.vol
+        };
+    }
+    /**
+     * Map a review outcome to a numeric score for Glicko-2.
+     *
+     * @param outcome Review result
+     * @returns Numeric 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 'FAIL': return 0.0;
+        }
+    }
+    /**
+     * Calculate confidence bounds from Glicko-2 parameters.
+     * Returns a proper statistical confidence interval.
+     *
+     * @param rating Current skill level rating
+     * @param ratingDeviation Rating deviation (standard deviation of rating)
+     * @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) {
+        // 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: rating + z * ratingDeviation
+        };
+    }
+    /**
+     * Create a default skill level for a new user.
+     * Starts at rating 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)
+     * @returns New SkillLevel object
+     */
+    static createDefault(initialRatingDeviation = 50, initialVolatility = 0.06) {
+        return {
+            rating: 0,
+            rating_deviation: initialRatingDeviation,
+            volatility: initialVolatility
+        };
+    }
+    /**
+     * 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)
+     */
+    static isHighConfidence(ratingDeviation, threshold = 15) {
+        return ratingDeviation < threshold;
+    }
+}
+exports.SkillLevelModel = SkillLevelModel;

package/dist/models/Streaks.js

@@ -94,10 +94,10 @@ class Streaks {
             }
         }
         // Calculate monthly streak
-        // Extract YYYY-MM from CompactDate (format: YYYY-MM-DD)
+        // Extract YYYYMM from CompactDate
         const monthlyActivity = new Set();
         for (const date of activityDates) {
-            const month = date.substring(0, 7); // Extract YYYY-MM
+            const month = shaxpir_common_1.Time.getYearMonth(date);
             monthlyActivity.add(month);
         }
         const sortedMonths = Array.from(monthlyActivity).sort();
@@ -110,10 +110,7 @@ class Streaks {
             }
             else {
                 // Check if consecutive month
-                const [lastYear, lastMonthNum] = lastMonth.split('-').map(Number);
-                const [currentYear, currentMonthNum] = month.split('-').map(Number);
-                if ((currentYear === lastYear && currentMonthNum === lastMonthNum + 1) ||
-                    (currentYear === lastYear + 1 && lastMonthNum === 12 && currentMonthNum === 1)) {
+                if (shaxpir_common_1.Time.areConsecutiveMonths(lastMonth, month)) {
                     monthlyStreak++;
                 }
                 else {
@@ -123,23 +120,13 @@ class Streaks {
             lastMonth = month;
         }
         // Check if current month streak is active
-        const currentMonth = today.substring(0, 7); // Extract YYYY-MM
+        const currentMonth = shaxpir_common_1.Time.getYearMonth(today);
         const lastActiveMonth = sortedMonths[sortedMonths.length - 1];
         const lastMonthDate = shaxpir_common_1.Time.plus(today, -30, 'days');
-        const previousMonth = shaxpir_common_1.Time.dateFrom(lastMonthDate).substring(0, 7);
+        const previousMonth = shaxpir_common_1.Time.getYearMonth(shaxpir_common_1.Time.dateFrom(lastMonthDate));
         if (lastActiveMonth === currentMonth || lastActiveMonth === previousMonth) {
             monthlyCurrent = monthlyStreak;
         }
-        // Get week string for last activity (ISO week format)
-        const getWeekString = (date) => {
-            // Simple week calculation: YYYY-Www where ww is week of year
-            const [year, month, day] = date.split('-').map(Number);
-            const dateObj = new Date(year, month - 1, day);
-            const startOfYear = new Date(year, 0, 1);
-            const dayOfYear = Math.floor((dateObj.getTime() - startOfYear.getTime()) / (24 * 60 * 60 * 1000)) + 1;
-            const weekNumber = Math.ceil(dayOfYear / 7);
-            return `${year}-W${weekNumber.toString().padStart(2, '0')}`;
-        };
         // We know lastDate has a value since activityDates.length > 0
         const finalLastDate = lastDate || activityDates[activityDates.length - 1];
         return {
@@ -155,8 +142,8 @@ class Streaks {
             },
             last_activity: {
                 date: finalLastDate,
-                week: getWeekString(finalLastDate),
-                month: finalLastDate.substring(0, 7)
+                week: shaxpir_common_1.Time.getWeekString(finalLastDate),
+                month: shaxpir_common_1.Time.getYearMonth(finalLastDate)
             },
             total_days: activityDates.length
         };

package/dist/models/index.d.ts

@@ -20,6 +20,7 @@ export * from './Profile';
 export * from './Progress';
 export * from './Review';
 export * from './Session';
+export * from './SkillLevel';
 export * from './Social';
 export * from './Streaks';
 export * from './Term';

package/dist/models/index.js

@@ -37,6 +37,7 @@ __exportStar(require("./Profile"), exports);
 __exportStar(require("./Progress"), exports);
 __exportStar(require("./Review"), exports);
 __exportStar(require("./Session"), exports);
+__exportStar(require("./SkillLevel"), exports);
 __exportStar(require("./Social"), exports);
 __exportStar(require("./Streaks"), exports);
 __exportStar(require("./Term"), exports);

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@shaxpir/duiduidui-models",
-  "version": "1.7.5",
+  "version": "1.8.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/shaxpir/duiduidui-models"
   },
   "scripts": {
     "build": "tsc",
-    "test": "mocha tests",
-    "test:watch": "mocha -w tests"
+    "test": "npm run build && mocha -r ts-node/register tests/**/*.ts",
+    "test:watch": "npm run build && mocha -r ts-node/register -w tests/**/*.ts"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,16 +18,20 @@
   "dependencies": {
     "@shaxpir/duiduidui-models": "^1.4.14",
     "@shaxpir/sharedb": "^6.0.6",
-    "@shaxpir/shaxpir-common": "1.4.0",
+    "@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"
   },
   "devDependencies": {
+    "@types/chai": "^5.2.3",
     "@types/lodash": "^4.17.20",
+    "@types/mocha": "^10.0.10",
     "@types/node": "^18.0.50",
     "chai": "^4.3.7",
     "mocha": "^10.2.0",
+    "ts-node": "^10.9.2",
     "tslint": "^5.12.1",
     "typescript": "latest"
   }