@shaxpir/duiduidui-models 1.4.26 → 1.4.27

package/dist/models/BayesianScore.d.ts

@@ -1,9 +1,28 @@
 import { ReviewResult } from "./Review";
+export interface Bounds {
+    lower: number;
+    upper: number;
+}
 export interface BayesianScore {
     alpha: number;
     beta: number;
     theta: number;
+    uncertainty: number;
 }
 export declare class BayesianScoreModel {
     static apply(prevScore: BayesianScore, result: ReviewResult, weight: number): BayesianScore;
+    /**
+     * Calculate uncertainty for a given Bayesian score.
+     * Higher values indicate less confidence in the theta estimate.
+     */
+    static getUncertainty(score: BayesianScore): number;
+    /**
+     * Calculate confidence interval for theta estimate.
+     * Uses properties of the Beta distribution to estimate bounds.
+     */
+    static getConfidenceInterval(score: BayesianScore, confidence?: number): Bounds;
+    /**
+     * Check if we have high confidence in this score (low uncertainty).
+     */
+    static isHighConfidence(score: BayesianScore, threshold?: number): boolean;
 }

package/dist/models/BayesianScore.js

@@ -21,7 +21,37 @@ class BayesianScoreModel {
             nextScore.beta += (weight * 1.0);
         }
         nextScore.theta = nextScore.alpha / (nextScore.alpha + nextScore.beta);
+        nextScore.uncertainty = BayesianScoreModel.getUncertainty(nextScore);
         return nextScore;
     }
+    /**
+     * Calculate uncertainty for a given Bayesian score.
+     * Higher values indicate less confidence in the theta estimate.
+     */
+    static getUncertainty(score) {
+        return 1 / (score.alpha + score.beta + 1);
+    }
+    /**
+     * Calculate confidence interval for theta estimate.
+     * Uses properties of the Beta distribution to estimate bounds.
+     */
+    static getConfidenceInterval(score, confidence = 0.95) {
+        // Calculate variance of Beta distribution
+        const variance = (score.alpha * score.beta) /
+            ((score.alpha + score.beta) ** 2 * (score.alpha + score.beta + 1));
+        const stdDev = Math.sqrt(variance);
+        // Z-scores for confidence levels
+        const z = confidence === 0.95 ? 1.96 : confidence === 0.99 ? 2.58 : 1.96;
+        return {
+            lower: Math.max(0, score.theta - z * stdDev),
+            upper: Math.min(1, score.theta + z * stdDev)
+        };
+    }
+    /**
+     * Check if we have high confidence in this score (low uncertainty).
+     */
+    static isHighConfidence(score, threshold = 0.1) {
+        return score.uncertainty < threshold;
+    }
 }
 exports.BayesianScoreModel = BayesianScoreModel;

package/dist/models/Phrase.d.ts

@@ -6,14 +6,14 @@ export interface PhraseExample {
     text: string;
     pinyin: string;
     translation: string;
-    learn_rank: number;
+    difficulty: number;
     sense_rank: number;
 }
 export interface Phrase {
     text: string;
     hanzi_count: number;
     sense_rank: number;
-    learn_rank: number;
+    difficulty: number;
     pinyin: string;
     pinyin_tokenized: string;
     transliteration: string;

package/dist/models/Progress.d.ts

@@ -1,16 +1,21 @@
 import { Doc } from '@shaxpir/sharedb/lib/client';
 import { CompactDateTime } from "@shaxpir/shaxpir-common";
 import { ShareSync } from '../repo';
-import { BayesianScore } from './BayesianScore';
+import { BayesianScore, Bounds } from './BayesianScore';
 import { Content, ContentBody, ContentId, ContentMeta } from "./Content";
 export interface PhraseProgress extends BayesianScore {
     text: string;
     sense_rank: number;
-    learn_rank: number;
+    difficulty: number;
     last_review_utc?: CompactDateTime;
 }
+export interface SkillLevel {
+    value: number;
+    uncertainty: number;
+    bounds: Bounds;
+}
 export interface ProgressPayload {
-    user_rank: number;
+    skill_level: SkillLevel;
     phrases: Record<string, PhraseProgress>;
     cognitive_load: number;
 }
@@ -23,10 +28,15 @@ export declare class Progress extends Content {
     static create(userId: ContentId): Progress;
     constructor(doc: Doc, shouldAcquire: boolean, shareSync: ShareSync);
     get payload(): ProgressPayload;
-    getUserRank(): number;
+    getSkillLevel(): SkillLevel;
+    getSkillLevelValue(): number;
+    getSkillLevelUncertainty(): number;
+    getSkillLevelBounds(): Bounds;
+    needsCalibration(): boolean;
     getCognitiveLoad(): number;
     getPhrases(): Record<string, PhraseProgress>;
-    setUserRank(value: number): void;
+    setSkillLevel(skillLevel: SkillLevel): void;
+    setSkillLevelValue(value: number): void;
     setCognitiveLoad(value: number): void;
     updatePhraseProgress(phraseId: string, progress: PhraseProgress): void;
     updateMultiplePhrases(updates: Record<string, PhraseProgress>): void;

package/dist/models/Progress.js

@@ -23,7 +23,14 @@ class Progress extends Content_1.Content {
                 updated_at: now
             },
             payload: {
-                user_rank: 0,
+                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
+                    }
+                },
                 phrases: {},
                 cognitive_load: 0
             }
@@ -36,9 +43,26 @@ class Progress extends Content_1.Content {
         this.checkDisposed("Progress.payload");
         return this.doc.data.payload;
     }
-    getUserRank() {
-        this.checkDisposed("Progress.getUserRank");
-        return this.payload.user_rank;
+    getSkillLevel() {
+        this.checkDisposed("Progress.getSkillLevel");
+        return this.payload.skill_level;
+    }
+    getSkillLevelValue() {
+        this.checkDisposed("Progress.getSkillLevelValue");
+        return this.payload.skill_level.value;
+    }
+    getSkillLevelUncertainty() {
+        this.checkDisposed("Progress.getSkillLevelUncertainty");
+        return this.payload.skill_level.uncertainty;
+    }
+    getSkillLevelBounds() {
+        this.checkDisposed("Progress.getSkillLevelBounds");
+        return this.payload.skill_level.bounds;
+    }
+    needsCalibration() {
+        this.checkDisposed("Progress.needsCalibration");
+        // High uncertainty means we need more data to calibrate user level
+        return this.payload.skill_level.uncertainty > 50;
     }
     getCognitiveLoad() {
         this.checkDisposed("Progress.getCognitiveLoad");
@@ -48,11 +72,17 @@ class Progress extends Content_1.Content {
         this.checkDisposed("Progress.getPhrases");
         return this.payload.phrases;
     }
-    setUserRank(value) {
-        this.checkDisposed("Progress.setUserRank");
-        if (this.payload.user_rank !== value) {
+    setSkillLevel(skillLevel) {
+        this.checkDisposed("Progress.setSkillLevel");
+        const batch = new Operation_1.BatchOperation(this);
+        batch.setPathValue(['payload', 'skill_level'], skillLevel);
+        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', 'user_rank'], value);
+            batch.setPathValue(['payload', 'skill_level', 'value'], value);
             batch.commit();
         }
     }

package/dist/models/Term.d.ts

@@ -8,7 +8,7 @@ import { ShareSync } from '../repo';
 export interface TermPayload extends BayesianScore {
     text: string;
     sense_rank: number;
-    learn_rank: number;
+    difficulty: number;
     phrase_id: number | null;
     starred_at: CompactDateTime | null;
     hanzi_count?: number;
@@ -31,13 +31,13 @@ export declare class Term extends Content {
     static makeTermId(userId: ContentId, text: string, senseRank: number): ContentId;
     private _reviewsView;
     constructor(doc: Doc, shouldAcquire: boolean, shareSync: ShareSync);
-    static forUserPhrase(userId: ContentId, text: string, senseRank: number, learnRank: number, phraseId?: number): Term;
+    static forUserPhrase(userId: ContentId, text: string, senseRank: number, difficulty: number, phraseId?: number): Term;
     static forUserPhrase(userId: ContentId, phrase: Phrase): Term;
     static forBuiltinPhrase(userId: ContentId, phrase: BuiltInPhrase): Term;
     get payload(): TermPayload;
     getText(): string;
     getSenseRank(): number;
-    getLearnRank(): number;
+    getDifficulty(): number;
     getAlpha(): number;
     getBeta(): number;
     getTheta(): number;

package/dist/models/Term.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Term = void 0;
 const shaxpir_common_1 = require("@shaxpir/shaxpir-common");
+const BayesianScore_1 = require("./BayesianScore");
 const Content_1 = require("./Content");
 const ContentKind_1 = require("./ContentKind");
 const repo_1 = require("../repo");
@@ -15,7 +16,7 @@ class Term extends Content_1.Content {
         super(doc, shouldAcquire, shareSync);
         this._reviewsView = new ArrayView_1.ArrayView(this, ['payload', 'reviews']);
     }
-    static forUserPhrase(userId, textOrPhrase, senseRank, learnRank, phraseId) {
+    static forUserPhrase(userId, textOrPhrase, senseRank, difficulty, phraseId) {
         const now = shaxpir_common_1.ClockService.getClock().now();
         // Handle overloaded parameters
         let phrase;
@@ -24,7 +25,7 @@ class Term extends Content_1.Content {
             phrase = {
                 text: textOrPhrase,
                 sense_rank: senseRank,
-                learn_rank: learnRank,
+                difficulty: difficulty,
                 hanzi_count: textOrPhrase.length,
                 pinyin: '',
                 pinyin_tokenized: '',
@@ -54,7 +55,7 @@ class Term extends Content_1.Content {
                 text: phrase.text,
                 sense_rank: phrase.sense_rank,
                 hanzi_count: phrase.hanzi_count,
-                learn_rank: phrase.learn_rank,
+                difficulty: phrase.difficulty,
                 pinyin: phrase.pinyin,
                 pinyin_tokenized: phrase.pinyin_tokenized,
                 transliteration: phrase.transliteration,
@@ -67,6 +68,7 @@ class Term extends Content_1.Content {
                 alpha: 0.5,
                 beta: 0.5,
                 theta: 0.5,
+                uncertainty: BayesianScore_1.BayesianScoreModel.getUncertainty({ alpha: 0.5, beta: 0.5, theta: 0.5, uncertainty: 0 }),
                 reviews: []
             }
         });
@@ -86,13 +88,14 @@ class Term extends Content_1.Content {
             payload: {
                 text: phrase.text,
                 sense_rank: phrase.sense_rank,
-                learn_rank: phrase.learn_rank,
+                difficulty: phrase.difficulty,
                 phrase_id: phrase.id,
                 starred_at: null,
                 tags: [],
                 alpha: 1,
                 beta: 1,
                 theta: 0.5,
+                uncertainty: BayesianScore_1.BayesianScoreModel.getUncertainty({ alpha: 1, beta: 1, theta: 0.5, uncertainty: 0 }),
                 reviews: []
             }
         });
@@ -109,9 +112,9 @@ class Term extends Content_1.Content {
         this.checkDisposed("Term.getSenseRank");
         return this.payload.sense_rank;
     }
-    getLearnRank() {
-        this.checkDisposed("Term.getLearnRank");
-        return this.payload.learn_rank;
+    getDifficulty() {
+        this.checkDisposed("Term.getDifficulty");
+        return this.payload.difficulty;
     }
     getAlpha() {
         this.checkDisposed("Term.getAlpha");
@@ -147,6 +150,7 @@ class Term extends Content_1.Content {
         batch.setPathValue(['payload', 'alpha'], alpha);
         batch.setPathValue(['payload', 'beta'], beta);
         batch.setPathValue(['payload', 'theta'], theta);
+        batch.setPathValue(['payload', 'uncertainty'], BayesianScore_1.BayesianScoreModel.getUncertainty({ alpha, beta, theta, uncertainty: 0 }));
         batch.commit();
     }
     addReview(review) {

package/package.json

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