@shaxpir/duiduidui-models 1.9.22 → 1.9.26

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/dist/util/DifficultyRange.d.ts

@@ -0,0 +1,60 @@
+import { Conditions } from '../models/Condition';
+/**
+ * Represents a difficulty range with guaranteed min (defaults to 0).
+ * Used for intersecting pool difficulty ranges with Collection constraints.
+ */
+export interface DifficultyRange {
+    min: number;
+    max: number | undefined;
+}
+/**
+ * Extracts difficulty constraints from Conditions.
+ *
+ * Checks the 'all' section for difficulty conditions since that's where
+ * Collection-level constraints are placed (they must all be satisfied).
+ *
+ * Exploits the invariant that difficulty and skill level are always >= 0,
+ * so min defaults to 0 when not specified.
+ *
+ * @param conditions - The conditions to search
+ * @returns DifficultyRange if a difficulty condition is found, null otherwise
+ */
+export declare function extractDifficultyConstraints(conditions?: Conditions): DifficultyRange | null;
+/**
+ * Result of intersecting difficulty ranges.
+ */
+export interface DifficultyRangeIntersection {
+    /** The effective minimum difficulty to use */
+    min: number;
+    /** The effective maximum difficulty to use */
+    max: number;
+    /** True if a valid intersection was found, false if fell back to Collection range */
+    usedIntersection: boolean;
+    /** True if Collection had a difficulty constraint */
+    hadCollectionConstraint: boolean;
+}
+/**
+ * Calculates the intersection of a pool's difficulty range with Collection constraints.
+ *
+ * If no intersection exists (ranges are disjoint), returns the Collection's range
+ * since the Collection constraints take precedence over skill-based calculations.
+ *
+ * @param poolMin - The pool's calculated minimum difficulty
+ * @param poolMax - The pool's calculated maximum difficulty
+ * @param collectionRange - The Collection's difficulty constraints (if any)
+ * @returns The effective range to use for queries, plus metadata
+ */
+export declare function intersectDifficultyRanges(poolMin: number, poolMax: number, collectionRange: DifficultyRange | null): DifficultyRangeIntersection;
+/**
+ * Checks if a difficulty value falls within a range.
+ *
+ * Useful for in-memory filtering in strategies that don't use database queries
+ * (ReinforcementPoolStrategy, StalePoolStrategy, DecompositionPoolStrategy).
+ *
+ * Uses half-open interval semantics: min is inclusive (>=), max is exclusive (<).
+ *
+ * @param difficulty - The difficulty value to check
+ * @param range - The range to check against (null means no constraint)
+ * @returns true if difficulty is within range or no range specified
+ */
+export declare function isWithinDifficultyRange(difficulty: number, range: DifficultyRange | null): boolean;

package/dist/util/DifficultyRange.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractDifficultyConstraints = extractDifficultyConstraints;
+exports.intersectDifficultyRanges = intersectDifficultyRanges;
+exports.isWithinDifficultyRange = isWithinDifficultyRange;
+/**
+ * Extracts difficulty constraints from Conditions.
+ *
+ * Checks the 'all' section for difficulty conditions since that's where
+ * Collection-level constraints are placed (they must all be satisfied).
+ *
+ * Exploits the invariant that difficulty and skill level are always >= 0,
+ * so min defaults to 0 when not specified.
+ *
+ * @param conditions - The conditions to search
+ * @returns DifficultyRange if a difficulty condition is found, null otherwise
+ */
+function extractDifficultyConstraints(conditions) {
+    if (!conditions?.all)
+        return null;
+    for (const condition of conditions.all) {
+        if (condition.type === 'difficulty') {
+            const diffCondition = condition;
+            return {
+                min: diffCondition.min ?? 0,
+                max: diffCondition.max
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Calculates the intersection of a pool's difficulty range with Collection constraints.
+ *
+ * If no intersection exists (ranges are disjoint), returns the Collection's range
+ * since the Collection constraints take precedence over skill-based calculations.
+ *
+ * @param poolMin - The pool's calculated minimum difficulty
+ * @param poolMax - The pool's calculated maximum difficulty
+ * @param collectionRange - The Collection's difficulty constraints (if any)
+ * @returns The effective range to use for queries, plus metadata
+ */
+function intersectDifficultyRanges(poolMin, poolMax, collectionRange) {
+    // No Collection constraint - use pool's range as-is
+    if (!collectionRange) {
+        return {
+            min: poolMin,
+            max: poolMax,
+            usedIntersection: true,
+            hadCollectionConstraint: false
+        };
+    }
+    // Calculate intersection
+    const intersectMin = Math.max(poolMin, collectionRange.min);
+    const intersectMax = collectionRange.max !== undefined
+        ? Math.min(poolMax, collectionRange.max)
+        : poolMax; // No upper bound on Collection, use pool's max
+    // Check if intersection is valid (non-empty range)
+    if (intersectMin < intersectMax) {
+        return {
+            min: intersectMin,
+            max: intersectMax,
+            usedIntersection: true,
+            hadCollectionConstraint: true
+        };
+    }
+    // No valid intersection - fall back to Collection's range
+    return {
+        min: collectionRange.min,
+        max: collectionRange.max ?? poolMax, // Use pool max if Collection has no upper bound
+        usedIntersection: false,
+        hadCollectionConstraint: true
+    };
+}
+/**
+ * Checks if a difficulty value falls within a range.
+ *
+ * Useful for in-memory filtering in strategies that don't use database queries
+ * (ReinforcementPoolStrategy, StalePoolStrategy, DecompositionPoolStrategy).
+ *
+ * Uses half-open interval semantics: min is inclusive (>=), max is exclusive (<).
+ *
+ * @param difficulty - The difficulty value to check
+ * @param range - The range to check against (null means no constraint)
+ * @returns true if difficulty is within range or no range specified
+ */
+function isWithinDifficultyRange(difficulty, range) {
+    if (!range)
+        return true;
+    if (difficulty < range.min)
+        return false;
+    if (range.max !== undefined && difficulty >= range.max)
+        return false;
+    return true;
+}

package/dist/util/index.d.ts

@@ -1,6 +1,7 @@
 export * from './AvatarUri';
 export * from './ConditionMatcher';
 export * from './Database';
+export * from './DifficultyRange';
 export * from './Encryption';
 export * from './Logging';
 export * from './SenseRankEncoder';

package/dist/util/index.js

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./AvatarUri"), exports);
 __exportStar(require("./ConditionMatcher"), exports);
 __exportStar(require("./Database"), exports);
+__exportStar(require("./DifficultyRange"), exports);
 __exportStar(require("./Encryption"), exports);
 __exportStar(require("./Logging"), exports);
 __exportStar(require("./SenseRankEncoder"), exports);

package/package.json

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