@contractspec/module.learning-journey 1.57.0 → 1.59.0

package/dist/browser/engines/streak.js

@@ -0,0 +1,159 @@
+// src/engines/streak.ts
+var DEFAULT_STREAK_CONFIG = {
+  timezone: "UTC",
+  freezesPerMonth: 2,
+  maxFreezes: 5,
+  gracePeriodHours: 4
+};
+
+class StreakEngine {
+  config;
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_STREAK_CONFIG, ...config };
+  }
+  update(state, now = new Date) {
+    const todayDate = this.getDateString(now);
+    const result = {
+      state: { ...state },
+      streakMaintained: false,
+      streakLost: false,
+      freezeUsed: false,
+      newStreak: false,
+      daysMissed: 0
+    };
+    if (!state.lastActivityDate) {
+      result.state.currentStreak = 1;
+      result.state.longestStreak = Math.max(1, state.longestStreak);
+      result.state.lastActivityAt = now;
+      result.state.lastActivityDate = todayDate;
+      result.newStreak = true;
+      result.streakMaintained = true;
+      return result;
+    }
+    if (state.lastActivityDate === todayDate) {
+      result.state.lastActivityAt = now;
+      result.streakMaintained = true;
+      return result;
+    }
+    const daysSinceActivity = this.getDaysBetween(state.lastActivityDate, todayDate);
+    if (daysSinceActivity === 1) {
+      result.state.currentStreak = state.currentStreak + 1;
+      result.state.longestStreak = Math.max(result.state.currentStreak, state.longestStreak);
+      result.state.lastActivityAt = now;
+      result.state.lastActivityDate = todayDate;
+      result.streakMaintained = true;
+      return result;
+    }
+    result.daysMissed = daysSinceActivity - 1;
+    const freezesNeeded = result.daysMissed;
+    if (freezesNeeded <= state.freezesRemaining) {
+      result.state.freezesRemaining = state.freezesRemaining - freezesNeeded;
+      result.state.freezeUsedAt = now;
+      result.state.currentStreak = state.currentStreak + 1;
+      result.state.longestStreak = Math.max(result.state.currentStreak, state.longestStreak);
+      result.state.lastActivityAt = now;
+      result.state.lastActivityDate = todayDate;
+      result.freezeUsed = true;
+      result.streakMaintained = true;
+      return result;
+    }
+    result.streakLost = true;
+    result.state.currentStreak = 1;
+    result.state.lastActivityAt = now;
+    result.state.lastActivityDate = todayDate;
+    result.newStreak = true;
+    return result;
+  }
+  checkStatus(state, now = new Date) {
+    if (!state.lastActivityDate) {
+      return {
+        isActive: false,
+        willExpireAt: null,
+        canUseFreeze: false,
+        daysUntilExpiry: 0
+      };
+    }
+    const todayDate = this.getDateString(now);
+    const daysSinceActivity = this.getDaysBetween(state.lastActivityDate, todayDate);
+    if (daysSinceActivity === 0) {
+      const tomorrow = this.addDays(now, 1);
+      tomorrow.setHours(23, 59, 59, 999);
+      return {
+        isActive: true,
+        willExpireAt: tomorrow,
+        canUseFreeze: state.freezesRemaining > 0,
+        daysUntilExpiry: 1
+      };
+    }
+    if (daysSinceActivity === 1) {
+      const endOfDay = new Date(now);
+      endOfDay.setHours(23 + this.config.gracePeriodHours, 59, 59, 999);
+      return {
+        isActive: true,
+        willExpireAt: endOfDay,
+        canUseFreeze: state.freezesRemaining > 0,
+        daysUntilExpiry: 0
+      };
+    }
+    const missedDays = daysSinceActivity - 1;
+    return {
+      isActive: missedDays <= state.freezesRemaining,
+      willExpireAt: null,
+      canUseFreeze: missedDays <= state.freezesRemaining,
+      daysUntilExpiry: -missedDays
+    };
+  }
+  useFreeze(state, now = new Date) {
+    if (state.freezesRemaining <= 0) {
+      return null;
+    }
+    return {
+      ...state,
+      freezesRemaining: state.freezesRemaining - 1,
+      freezeUsedAt: now
+    };
+  }
+  awardMonthlyFreezes(state) {
+    return {
+      ...state,
+      freezesRemaining: Math.min(state.freezesRemaining + this.config.freezesPerMonth, this.config.maxFreezes)
+    };
+  }
+  getInitialState() {
+    return {
+      currentStreak: 0,
+      longestStreak: 0,
+      lastActivityAt: null,
+      lastActivityDate: null,
+      freezesRemaining: this.config.freezesPerMonth,
+      freezeUsedAt: null
+    };
+  }
+  getMilestones(currentStreak) {
+    const milestones = [3, 7, 14, 30, 60, 90, 180, 365, 500, 1000];
+    const achieved = milestones.filter((m) => currentStreak >= m);
+    const next = milestones.find((m) => currentStreak < m) ?? null;
+    return { achieved, next };
+  }
+  getDateString(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+  }
+  getDaysBetween(dateStr1, dateStr2) {
+    const date1 = new Date(dateStr1);
+    const date2 = new Date(dateStr2);
+    const diffTime = date2.getTime() - date1.getTime();
+    return Math.floor(diffTime / (1000 * 60 * 60 * 24));
+  }
+  addDays(date, days) {
+    return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
+  }
+}
+var streakEngine = new StreakEngine;
+export {
+  streakEngine,
+  StreakEngine,
+  DEFAULT_STREAK_CONFIG
+};

package/dist/browser/engines/xp.js

@@ -0,0 +1,171 @@
+// src/engines/xp.ts
+var DEFAULT_XP_CONFIG = {
+  baseValues: {
+    lesson_complete: 10,
+    quiz_pass: 20,
+    quiz_perfect: 50,
+    flashcard_review: 1,
+    course_complete: 200,
+    module_complete: 50,
+    streak_bonus: 5,
+    achievement_unlock: 0,
+    daily_goal_complete: 15,
+    first_lesson: 25,
+    onboarding_step: 5,
+    onboarding_complete: 50
+  },
+  scoreThresholds: [
+    { min: 90, multiplier: 1.5 },
+    { min: 80, multiplier: 1.25 },
+    { min: 70, multiplier: 1 },
+    { min: 60, multiplier: 0.75 },
+    { min: 0, multiplier: 0.5 }
+  ],
+  streakTiers: [
+    { days: 365, bonus: 50 },
+    { days: 180, bonus: 30 },
+    { days: 90, bonus: 20 },
+    { days: 30, bonus: 15 },
+    { days: 14, bonus: 10 },
+    { days: 7, bonus: 5 },
+    { days: 3, bonus: 2 },
+    { days: 1, bonus: 0 }
+  ],
+  perfectScoreMultiplier: 1.5,
+  firstAttemptBonus: 10,
+  retryPenalty: 0.5,
+  speedBonusMultiplier: 1.2,
+  speedBonusThreshold: 0.8
+};
+
+class XPEngine {
+  config;
+  constructor(config = {}) {
+    this.config = {
+      ...DEFAULT_XP_CONFIG,
+      ...config,
+      baseValues: { ...DEFAULT_XP_CONFIG.baseValues, ...config.baseValues },
+      scoreThresholds: config.scoreThresholds || DEFAULT_XP_CONFIG.scoreThresholds,
+      streakTiers: config.streakTiers || DEFAULT_XP_CONFIG.streakTiers
+    };
+  }
+  calculate(input) {
+    const breakdown = [];
+    const baseXp = input.baseXp ?? this.config.baseValues[input.activity];
+    let totalXp = baseXp;
+    breakdown.push({
+      source: "base",
+      amount: baseXp
+    });
+    if (input.score !== undefined) {
+      const scoreMultiplier = this.getScoreMultiplier(input.score);
+      if (scoreMultiplier !== 1) {
+        const scoreBonus = Math.round(baseXp * (scoreMultiplier - 1));
+        totalXp += scoreBonus;
+        breakdown.push({
+          source: "score_bonus",
+          amount: scoreBonus,
+          multiplier: scoreMultiplier
+        });
+      }
+      if (input.score === 100) {
+        const perfectBonus = Math.round(baseXp * (this.config.perfectScoreMultiplier - 1));
+        totalXp += perfectBonus;
+        breakdown.push({
+          source: "perfect_score",
+          amount: perfectBonus,
+          multiplier: this.config.perfectScoreMultiplier
+        });
+      }
+    }
+    if (input.attemptNumber === 1 && !input.isRetry) {
+      totalXp += this.config.firstAttemptBonus;
+      breakdown.push({
+        source: "first_attempt",
+        amount: this.config.firstAttemptBonus
+      });
+    }
+    if (input.isRetry) {
+      const penalty = Math.round(totalXp * (1 - this.config.retryPenalty));
+      totalXp -= penalty;
+      breakdown.push({
+        source: "retry_penalty",
+        amount: -penalty,
+        multiplier: this.config.retryPenalty
+      });
+    }
+    if (input.currentStreak && input.currentStreak > 0) {
+      const streakBonus = this.getStreakBonus(input.currentStreak);
+      if (streakBonus > 0) {
+        totalXp += streakBonus;
+        breakdown.push({
+          source: "streak_bonus",
+          amount: streakBonus
+        });
+      }
+    }
+    if (baseXp > 0) {
+      totalXp = Math.max(1, totalXp);
+    }
+    return {
+      totalXp: Math.round(totalXp),
+      baseXp,
+      breakdown
+    };
+  }
+  calculateStreakBonus(currentStreak) {
+    const bonus = this.getStreakBonus(currentStreak);
+    return {
+      totalXp: bonus,
+      baseXp: bonus,
+      breakdown: [
+        {
+          source: "streak_bonus",
+          amount: bonus
+        }
+      ]
+    };
+  }
+  getXpForLevel(level) {
+    if (level <= 1)
+      return 0;
+    return Math.round(100 * Math.pow(level - 1, 1.5));
+  }
+  getLevelFromXp(totalXp) {
+    let level = 1;
+    let xpRequired = this.getXpForLevel(level + 1);
+    while (totalXp >= xpRequired && level < 1000) {
+      level++;
+      xpRequired = this.getXpForLevel(level + 1);
+    }
+    const xpForCurrentLevel = this.getXpForLevel(level);
+    const xpForNextLevel = this.getXpForLevel(level + 1);
+    return {
+      level,
+      xpInLevel: totalXp - xpForCurrentLevel,
+      xpForNextLevel: xpForNextLevel - xpForCurrentLevel
+    };
+  }
+  getScoreMultiplier(score) {
+    for (const threshold of this.config.scoreThresholds) {
+      if (score >= threshold.min) {
+        return threshold.multiplier;
+      }
+    }
+    return 1;
+  }
+  getStreakBonus(streak) {
+    for (const tier of this.config.streakTiers) {
+      if (streak >= tier.days) {
+        return tier.bonus;
+      }
+    }
+    return 0;
+  }
+}
+var xpEngine = new XPEngine;
+export {
+  xpEngine,
+  XPEngine,
+  DEFAULT_XP_CONFIG
+};

package/dist/browser/entities/ai.js

@@ -0,0 +1,343 @@
+// src/entities/ai.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var LearningStyleEnum = defineEntityEnum({
+  name: "LearningStyle",
+  values: ["VISUAL", "AUDITORY", "READING", "KINESTHETIC", "MIXED"],
+  schema: "lssm_learning",
+  description: "Preferred learning style."
+});
+var RecommendationTypeEnum = defineEntityEnum({
+  name: "RecommendationType",
+  values: [
+    "COURSE",
+    "LESSON",
+    "REVIEW",
+    "PRACTICE",
+    "ASSESSMENT",
+    "DECK"
+  ],
+  schema: "lssm_learning",
+  description: "Type of learning recommendation."
+});
+var LearnerProfileEntity = defineEntity({
+  name: "LearnerProfile",
+  description: "AI personalization profile for a learner.",
+  schema: "lssm_learning",
+  map: "learner_profile",
+  fields: {
+    id: field.id({ description: "Unique profile identifier" }),
+    learnerId: field.foreignKey({ description: "Learner" }),
+    learningStyle: field.enum("LearningStyle", {
+      default: "MIXED",
+      description: "Preferred learning style"
+    }),
+    preferredDifficulty: field.string({
+      default: '"adaptive"',
+      description: "Difficulty preference"
+    }),
+    preferredSessionLength: field.int({
+      default: 30,
+      description: "Preferred session length in minutes"
+    }),
+    interests: field.json({ isOptional: true, description: "Topic interests" }),
+    goals: field.json({ isOptional: true, description: "Learning goals" }),
+    pacePreference: field.string({
+      default: '"normal"',
+      description: "Learning pace: slow, normal, fast"
+    }),
+    bestTimeOfDay: field.string({
+      isOptional: true,
+      description: "Best time for learning"
+    }),
+    averageSessionLength: field.int({
+      isOptional: true,
+      description: "Average session length"
+    }),
+    daysActivePerWeek: field.int({
+      isOptional: true,
+      description: "Days active per week"
+    }),
+    avgQuizScore: field.int({
+      isOptional: true,
+      description: "Average quiz score"
+    }),
+    avgLessonCompletionTime: field.int({
+      isOptional: true,
+      description: "Avg lesson completion time"
+    }),
+    strengths: field.json({
+      isOptional: true,
+      description: "Identified strengths"
+    }),
+    weaknesses: field.json({
+      isOptional: true,
+      description: "Areas for improvement"
+    }),
+    lastAnalyzedAt: field.dateTime({
+      isOptional: true,
+      description: "Last AI analysis"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    learner: field.belongsTo("Learner", ["learnerId"], ["id"], {
+      onDelete: "Cascade"
+    })
+  },
+  indexes: [
+    index.unique(["learnerId"], { name: "learner_profile_unique" }),
+    index.on(["learningStyle"])
+  ],
+  enums: [LearningStyleEnum]
+});
+var SkillMapEntity = defineEntity({
+  name: "SkillMap",
+  description: "Maps learner proficiency across skills.",
+  schema: "lssm_learning",
+  map: "skill_map",
+  fields: {
+    id: field.id({ description: "Unique skill map identifier" }),
+    learnerId: field.foreignKey({ description: "Learner" }),
+    skillId: field.string({ description: "Skill identifier" }),
+    skillName: field.string({ description: "Skill name" }),
+    skillCategory: field.string({
+      isOptional: true,
+      description: "Skill category"
+    }),
+    level: field.int({ default: 0, description: "Proficiency level (0-100)" }),
+    confidence: field.decimal({
+      default: 0.5,
+      description: "Confidence in assessment"
+    }),
+    lessonsCompleted: field.int({
+      default: 0,
+      description: "Related lessons completed"
+    }),
+    quizzesCompleted: field.int({
+      default: 0,
+      description: "Related quizzes completed"
+    }),
+    practiceTime: field.int({
+      default: 0,
+      description: "Practice time in minutes"
+    }),
+    lastPracticedAt: field.dateTime({
+      isOptional: true,
+      description: "Last practice time"
+    }),
+    learningVelocity: field.decimal({
+      isOptional: true,
+      description: "Learning speed for this skill"
+    }),
+    predictedTimeToMastery: field.int({
+      isOptional: true,
+      description: "Predicted time to mastery (minutes)"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    learner: field.belongsTo("Learner", ["learnerId"], ["id"], {
+      onDelete: "Cascade"
+    })
+  },
+  indexes: [
+    index.unique(["learnerId", "skillId"], { name: "skill_map_unique" }),
+    index.on(["skillId", "level"]),
+    index.on(["learnerId", "level"])
+  ]
+});
+var LearningPathEntity = defineEntity({
+  name: "LearningPath",
+  description: "AI-generated personalized learning path.",
+  schema: "lssm_learning",
+  map: "learning_path",
+  fields: {
+    id: field.id({ description: "Unique path identifier" }),
+    learnerId: field.foreignKey({ description: "Learner" }),
+    name: field.string({ description: "Path name" }),
+    description: field.string({
+      isOptional: true,
+      description: "Path description"
+    }),
+    goal: field.string({ isOptional: true, description: "Path goal" }),
+    steps: field.json({ description: "Ordered list of learning steps" }),
+    currentStepIndex: field.int({
+      default: 0,
+      description: "Current step index"
+    }),
+    progress: field.int({ default: 0, description: "Completion percentage" }),
+    completedSteps: field.int({ default: 0, description: "Steps completed" }),
+    totalSteps: field.int({ default: 0, description: "Total steps" }),
+    generatedAt: field.dateTime({ description: "When path was generated" }),
+    adaptedFrom: field.string({
+      isOptional: true,
+      description: "Original path ID if adapted"
+    }),
+    generationParams: field.json({
+      isOptional: true,
+      description: "AI generation parameters"
+    }),
+    adaptationHistory: field.json({
+      isOptional: true,
+      description: "Path adaptation history"
+    }),
+    isActive: field.boolean({
+      default: true,
+      description: "Whether path is active"
+    }),
+    isCompleted: field.boolean({
+      default: false,
+      description: "Whether path is completed"
+    }),
+    startedAt: field.dateTime({
+      isOptional: true,
+      description: "When started"
+    }),
+    completedAt: field.dateTime({
+      isOptional: true,
+      description: "When completed"
+    }),
+    estimatedCompletionDate: field.dateTime({
+      isOptional: true,
+      description: "Estimated completion"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    learner: field.belongsTo("Learner", ["learnerId"], ["id"], {
+      onDelete: "Cascade"
+    })
+  },
+  indexes: [index.on(["learnerId", "isActive"]), index.on(["generatedAt"])]
+});
+var RecommendationEntity = defineEntity({
+  name: "Recommendation",
+  description: "AI-powered learning recommendation.",
+  schema: "lssm_learning",
+  map: "recommendation",
+  fields: {
+    id: field.id({ description: "Unique recommendation identifier" }),
+    learnerId: field.foreignKey({ description: "Learner" }),
+    type: field.enum("RecommendationType", {
+      description: "Recommendation type"
+    }),
+    itemId: field.string({ description: "Recommended item ID" }),
+    itemType: field.string({
+      description: "Item type (course, lesson, deck, etc.)"
+    }),
+    score: field.decimal({ description: "Recommendation score (0-1)" }),
+    confidence: field.decimal({ description: "Confidence in recommendation" }),
+    reason: field.string({ description: "Human-readable reason" }),
+    factors: field.json({
+      isOptional: true,
+      description: "Factors that contributed to recommendation"
+    }),
+    status: field.string({
+      default: '"pending"',
+      description: "Status: pending, viewed, accepted, dismissed"
+    }),
+    viewedAt: field.dateTime({ isOptional: true, description: "When viewed" }),
+    acceptedAt: field.dateTime({
+      isOptional: true,
+      description: "When accepted"
+    }),
+    dismissedAt: field.dateTime({
+      isOptional: true,
+      description: "When dismissed"
+    }),
+    feedback: field.string({ isOptional: true, description: "User feedback" }),
+    feedbackRating: field.int({
+      isOptional: true,
+      description: "Feedback rating (1-5)"
+    }),
+    expiresAt: field.dateTime({
+      isOptional: true,
+      description: "When recommendation expires"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    learner: field.belongsTo("Learner", ["learnerId"], ["id"], {
+      onDelete: "Cascade"
+    })
+  },
+  indexes: [
+    index.on(["learnerId", "status", "score"]),
+    index.on(["type", "status"]),
+    index.on(["expiresAt"])
+  ],
+  enums: [RecommendationTypeEnum]
+});
+var LearningGapEntity = defineEntity({
+  name: "LearningGap",
+  description: "Identified learning gap.",
+  schema: "lssm_learning",
+  map: "learning_gap",
+  fields: {
+    id: field.id({ description: "Unique gap identifier" }),
+    learnerId: field.foreignKey({ description: "Learner" }),
+    skillId: field.string({ description: "Skill with gap" }),
+    skillName: field.string({ description: "Skill name" }),
+    severity: field.string({
+      default: '"moderate"',
+      description: "Gap severity: minor, moderate, major"
+    }),
+    confidence: field.decimal({ description: "Confidence in gap detection" }),
+    evidence: field.json({ isOptional: true, description: "Evidence for gap" }),
+    relatedQuestions: field.json({
+      isOptional: true,
+      description: "Questions that revealed gap"
+    }),
+    suggestedRemediation: field.json({
+      isOptional: true,
+      description: "Suggested remediation"
+    }),
+    remediationProgress: field.int({
+      default: 0,
+      description: "Remediation progress"
+    }),
+    status: field.string({
+      default: '"open"',
+      description: "Status: open, in_progress, resolved"
+    }),
+    resolvedAt: field.dateTime({
+      isOptional: true,
+      description: "When resolved"
+    }),
+    detectedAt: field.dateTime({ description: "When gap was detected" }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    learner: field.belongsTo("Learner", ["learnerId"], ["id"], {
+      onDelete: "Cascade"
+    })
+  },
+  indexes: [
+    index.on(["learnerId", "status"]),
+    index.on(["skillId", "status"]),
+    index.on(["severity", "status"])
+  ]
+});
+var aiEntities = [
+  LearnerProfileEntity,
+  SkillMapEntity,
+  LearningPathEntity,
+  RecommendationEntity,
+  LearningGapEntity
+];
+var aiEnums = [LearningStyleEnum, RecommendationTypeEnum];
+export {
+  aiEnums,
+  aiEntities,
+  SkillMapEntity,
+  RecommendationTypeEnum,
+  RecommendationEntity,
+  LearningStyleEnum,
+  LearningPathEntity,
+  LearningGapEntity,
+  LearnerProfileEntity
+};