@vue-skuilder/db 0.1.16 → 0.1.18

package/src/core/navigators/interferenceMitigator.ts

@@ -0,0 +1,367 @@
+import type { ScheduledCard } from '../types/user';
+import type { CourseDBInterface } from '../interfaces/courseDB';
+import type { UserDBInterface } from '../interfaces/userDB';
+import { ContentNavigator } from './index';
+import type { WeightedCard } from './index';
+import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+import type { StudySessionReviewItem, StudySessionNewItem } from '..';
+import type { CardFilter, FilterContext } from './filters/types';
+import { toCourseElo } from '@vue-skuilder/common';
+
+/**
+ * Configuration for the InterferenceMitigator strategy.
+ *
+ * Course authors define explicit interference relationships between tags.
+ * The mitigator discourages introducing new concepts that interfere with
+ * currently immature learnings.
+ */
+/**
+ * A single interference group with its own decay coefficient.
+ */
+export interface InterferenceGroup {
+  /** Tags that interfere with each other in this group */
+  tags: string[];
+  /** How strongly these tags interfere (0-1, default: 0.8). Higher = stronger avoidance. */
+  decay?: number;
+}
+
+export interface InterferenceConfig {
+  /**
+   * Groups of tags that interfere with each other.
+   * Each group can have its own decay coefficient.
+   *
+   * Example: [
+   *   { tags: ["b", "d", "p"], decay: 0.9 },  // visual similarity - strong
+   *   { tags: ["d", "t"], decay: 0.7 },       // phonetic similarity - moderate
+   *   { tags: ["m", "n"], decay: 0.8 }
+   * ]
+   */
+  interferenceSets: InterferenceGroup[];
+
+  /**
+   * Threshold below which a tag is considered "immature" (still being learned).
+   * Immature tags trigger interference avoidance for their interference partners.
+   */
+  maturityThreshold?: {
+    /** Minimum interaction count to be considered mature (default: 10) */
+    minCount?: number;
+    /** Minimum ELO score to be considered mature (optional) */
+    minElo?: number;
+    /**
+     * Minimum elapsed time (in days) since first interaction to be considered mature.
+     * Prevents recent cramming success from indicating maturity.
+     * The skill should be "lindy" — maintained over time.
+     */
+    minElapsedDays?: number;
+  };
+
+  /**
+   * Default decay for groups that don't specify their own (0-1, default: 0.8).
+   */
+  defaultDecay?: number;
+}
+
+const DEFAULT_MIN_COUNT = 10;
+const DEFAULT_MIN_ELAPSED_DAYS = 3;
+const DEFAULT_INTERFERENCE_DECAY = 0.8;
+
+/**
+ * A filter strategy that avoids introducing confusable concepts simultaneously.
+ *
+ * When a user is learning a concept (tag is "immature"), this strategy reduces
+ * scores for cards tagged with interfering concepts. This encourages the system
+ * to introduce new content that is maximally distant from current learning focus.
+ *
+ * Example: While learning 'd', prefer introducing 'x' over 'b' (visual interference)
+ * or 't' (phonetic interference).
+ *
+ * Implements CardFilter for use in Pipeline architecture.
+ * Also extends ContentNavigator for backward compatibility.
+ */
+export default class InterferenceMitigatorNavigator extends ContentNavigator implements CardFilter {
+  private config: InterferenceConfig;
+  private _strategyData: ContentNavigationStrategyData;
+
+  /** Human-readable name for CardFilter interface */
+  name: string;
+
+  /** Precomputed map: tag -> set of { partner, decay } it interferes with */
+  private interferenceMap: Map<string, Array<{ partner: string; decay: number }>>;
+
+  constructor(
+    user: UserDBInterface,
+    course: CourseDBInterface,
+    _strategyData: ContentNavigationStrategyData
+  ) {
+    super(user, course, _strategyData);
+    this._strategyData = _strategyData;
+    this.config = this.parseConfig(_strategyData.serializedData);
+    this.interferenceMap = this.buildInterferenceMap();
+    this.name = _strategyData.name || 'Interference Mitigator';
+  }
+
+  private parseConfig(serializedData: string): InterferenceConfig {
+    try {
+      const parsed = JSON.parse(serializedData);
+      // Normalize legacy format (string[][]) to new format (InterferenceGroup[])
+      let sets: InterferenceGroup[] = parsed.interferenceSets || [];
+      if (sets.length > 0 && Array.isArray(sets[0])) {
+        // Legacy format: convert string[][] to InterferenceGroup[]
+        sets = (sets as unknown as string[][]).map((tags) => ({ tags }));
+      }
+
+      return {
+        interferenceSets: sets,
+        maturityThreshold: {
+          minCount: parsed.maturityThreshold?.minCount ?? DEFAULT_MIN_COUNT,
+          minElo: parsed.maturityThreshold?.minElo,
+          minElapsedDays: parsed.maturityThreshold?.minElapsedDays ?? DEFAULT_MIN_ELAPSED_DAYS,
+        },
+        defaultDecay: parsed.defaultDecay ?? DEFAULT_INTERFERENCE_DECAY,
+      };
+    } catch {
+      return {
+        interferenceSets: [],
+        maturityThreshold: {
+          minCount: DEFAULT_MIN_COUNT,
+          minElapsedDays: DEFAULT_MIN_ELAPSED_DAYS,
+        },
+        defaultDecay: DEFAULT_INTERFERENCE_DECAY,
+      };
+    }
+  }
+
+  /**
+   * Build a map from each tag to its interference partners with decay coefficients.
+   * If tags A, B, C are in an interference group with decay 0.8, then:
+   * - A interferes with B (decay 0.8) and C (decay 0.8)
+   * - B interferes with A (decay 0.8) and C (decay 0.8)
+   * - etc.
+   */
+  private buildInterferenceMap(): Map<string, Array<{ partner: string; decay: number }>> {
+    const map = new Map<string, Array<{ partner: string; decay: number }>>();
+
+    for (const group of this.config.interferenceSets) {
+      const decay = group.decay ?? this.config.defaultDecay ?? DEFAULT_INTERFERENCE_DECAY;
+
+      for (const tag of group.tags) {
+        if (!map.has(tag)) {
+          map.set(tag, []);
+        }
+        const partners = map.get(tag)!;
+        for (const other of group.tags) {
+          if (other !== tag) {
+            // Check if partner already exists (from overlapping groups)
+            const existing = partners.find((p) => p.partner === other);
+            if (existing) {
+              // Use the stronger (higher) decay
+              existing.decay = Math.max(existing.decay, decay);
+            } else {
+              partners.push({ partner: other, decay });
+            }
+          }
+        }
+      }
+    }
+
+    return map;
+  }
+
+  /**
+   * Get the set of tags that are currently immature for this user.
+   * A tag is immature if the user has interacted with it but hasn't
+   * reached the maturity threshold.
+   */
+  private async getImmatureTags(context: FilterContext): Promise<Set<string>> {
+    const immature = new Set<string>();
+
+    try {
+      const courseReg = await context.user.getCourseRegDoc(context.course.getCourseID());
+      const userElo = toCourseElo(courseReg.elo);
+
+      const minCount = this.config.maturityThreshold?.minCount ?? DEFAULT_MIN_COUNT;
+      const minElo = this.config.maturityThreshold?.minElo;
+
+      // TODO: To properly check elapsed time, we need access to first interaction timestamp.
+      // For now, we use count as a proxy (more interactions = more time elapsed).
+      // Future: query card history for earliest timestamp per tag.
+      const minElapsedDays =
+        this.config.maturityThreshold?.minElapsedDays ?? DEFAULT_MIN_ELAPSED_DAYS;
+      const minCountForElapsed = minElapsedDays * 2; // Rough proxy: ~2 interactions per day
+
+      for (const [tagId, tagElo] of Object.entries(userElo.tags)) {
+        // Only consider tags that have been started (count > 0)
+        if (tagElo.count === 0) continue;
+
+        // Check if below maturity threshold
+        const belowCount = tagElo.count < minCount;
+        const belowElo = minElo !== undefined && tagElo.score < minElo;
+        const belowElapsed = tagElo.count < minCountForElapsed; // Proxy for time
+
+        if (belowCount || belowElo || belowElapsed) {
+          immature.add(tagId);
+        }
+      }
+    } catch {
+      // If we can't get user data, assume no immature tags
+    }
+
+    return immature;
+  }
+
+  /**
+   * Get all tags that interfere with any immature tag, along with their decay coefficients.
+   * These are the tags we want to avoid introducing.
+   */
+  private getTagsToAvoid(immatureTags: Set<string>): Map<string, number> {
+    const avoid = new Map<string, number>();
+
+    for (const immatureTag of immatureTags) {
+      const partners = this.interferenceMap.get(immatureTag);
+      if (partners) {
+        for (const { partner, decay } of partners) {
+          // Avoid the partner, but not if it's also immature
+          // (if both are immature, we're already learning both)
+          if (!immatureTags.has(partner)) {
+            // Use the strongest (highest) decay if partner appears multiple times
+            const existing = avoid.get(partner) ?? 0;
+            avoid.set(partner, Math.max(existing, decay));
+          }
+        }
+      }
+    }
+
+    return avoid;
+  }
+
+  /**
+   * Get tags for a single card
+   */
+  private async getCardTags(cardId: string, course: CourseDBInterface): Promise<string[]> {
+    try {
+      const tagResponse = await course.getAppliedTags(cardId);
+      return tagResponse.rows.map((row) => row.value?.name || row.key).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Compute interference score reduction for a card.
+   * Returns: { multiplier, interfering tags, reason }
+   */
+  private computeInterferenceEffect(
+    cardTags: string[],
+    tagsToAvoid: Map<string, number>,
+    immatureTags: Set<string>
+  ): { multiplier: number; interferingTags: string[]; reason: string } {
+    if (tagsToAvoid.size === 0) {
+      return {
+        multiplier: 1.0,
+        interferingTags: [],
+        reason: 'No interference detected',
+      };
+    }
+
+    let multiplier = 1.0;
+    const interferingTags: string[] = [];
+
+    for (const tag of cardTags) {
+      const decay = tagsToAvoid.get(tag);
+      if (decay !== undefined) {
+        interferingTags.push(tag);
+        multiplier *= 1.0 - decay;
+      }
+    }
+
+    if (interferingTags.length === 0) {
+      return {
+        multiplier: 1.0,
+        interferingTags: [],
+        reason: 'No interference detected',
+      };
+    }
+
+    // Find which immature tags these interfere with
+    const causingTags = new Set<string>();
+    for (const tag of interferingTags) {
+      for (const immatureTag of immatureTags) {
+        const partners = this.interferenceMap.get(immatureTag);
+        if (partners?.some((p) => p.partner === tag)) {
+          causingTags.add(immatureTag);
+        }
+      }
+    }
+
+    const reason = `Interferes with immature tags ${Array.from(causingTags).join(', ')} (tags: ${interferingTags.join(', ')}, multiplier: ${multiplier.toFixed(2)})`;
+
+    return { multiplier, interferingTags, reason };
+  }
+
+  /**
+   * CardFilter.transform implementation.
+   *
+   * Apply interference-aware scoring. Cards with tags that interfere with
+   * immature learnings get reduced scores.
+   */
+  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+    // Identify what to avoid
+    const immatureTags = await this.getImmatureTags(context);
+    const tagsToAvoid = this.getTagsToAvoid(immatureTags);
+
+    // Adjust scores based on interference
+    const adjusted: WeightedCard[] = [];
+
+    for (const card of cards) {
+      const cardTags = await this.getCardTags(card.cardId, context.course);
+      const { multiplier, reason } = this.computeInterferenceEffect(
+        cardTags,
+        tagsToAvoid,
+        immatureTags
+      );
+      const finalScore = card.score * multiplier;
+
+      const action = multiplier < 1.0 ? 'penalized' : multiplier > 1.0 ? 'boosted' : 'passed';
+
+      adjusted.push({
+        ...card,
+        score: finalScore,
+        provenance: [
+          ...card.provenance,
+          {
+            strategy: 'interferenceMitigator',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || 'NAVIGATION_STRATEGY-interference',
+            action,
+            score: finalScore,
+            reason,
+          },
+        ],
+      });
+    }
+
+    return adjusted;
+  }
+
+  /**
+   * Legacy getWeightedCards - now throws as filters should not be used as generators.
+   *
+   * Use transform() via Pipeline instead.
+   */
+  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+    throw new Error(
+      'InterferenceMitigatorNavigator is a filter and should not be used as a generator. ' +
+        'Use Pipeline with a generator and this filter via transform().'
+    );
+  }
+
+  // Legacy methods - stub implementations since filters don't generate cards
+
+  async getNewCards(_n?: number): Promise<StudySessionNewItem[]> {
+    return [];
+  }
+
+  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
+    return [];
+  }
+}

package/src/core/navigators/relativePriority.ts

@@ -0,0 +1,267 @@
+import type { ScheduledCard } from '../types/user';
+import type { CourseDBInterface } from '../interfaces/courseDB';
+import type { UserDBInterface } from '../interfaces/userDB';
+import { ContentNavigator } from './index';
+import type { WeightedCard } from './index';
+import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+import type { StudySessionReviewItem, StudySessionNewItem } from '..';
+import type { CardFilter, FilterContext } from './filters/types';
+
+/**
+ * Configuration for the RelativePriority strategy.
+ *
+ * Course authors define priority weights for tags, allowing the system
+ * to prefer high-utility content (common, well-behaved patterns) over
+ * lower-utility content (rare, irregular patterns).
+ *
+ * Example use case: In phonics, prefer teaching 's' (common, consistent)
+ * before 'x' or 'z' (rare, sometimes irregular).
+ */
+export interface RelativePriorityConfig {
+  /**
+   * Map of tag ID to priority weight (0-1).
+   *
+   * 1.0 = highest priority (present first)
+   * 0.5 = neutral
+   * 0.0 = lowest priority (defer until later)
+   *
+   * Example:
+   * {
+   *   "letter-s": 0.95,
+   *   "letter-t": 0.90,
+   *   "letter-x": 0.10,
+   *   "letter-z": 0.05
+   * }
+   */
+  tagPriorities: { [tagId: string]: number };
+
+  /**
+   * Priority for tags not explicitly listed (default: 0.5).
+   * 0.5 means unlisted tags have neutral effect on scoring.
+   */
+  defaultPriority?: number;
+
+  /**
+   * How to combine priorities when a card has multiple tags.
+   *
+   * - 'max': Use the highest priority among the card's tags (default)
+   * - 'average': Average all tag priorities
+   * - 'min': Use the lowest priority (conservative)
+   */
+  combineMode?: 'max' | 'average' | 'min';
+
+  /**
+   * How strongly priority influences the final score (0-1, default: 0.5).
+   *
+   * At 0.0: Priority has no effect (pure delegate scoring)
+   * At 0.5: Priority can boost/reduce scores by up to 25%
+   * At 1.0: Priority can boost/reduce scores by up to 50%
+   *
+   * The boost factor formula: 1 + (priority - 0.5) * priorityInfluence
+   * - Priority 1.0 with influence 0.5 → boost of 1.25
+   * - Priority 0.5 with influence 0.5 → boost of 1.00 (neutral)
+   * - Priority 0.0 with influence 0.5 → boost of 0.75
+   */
+  priorityInfluence?: number;
+}
+
+const DEFAULT_PRIORITY = 0.5;
+const DEFAULT_PRIORITY_INFLUENCE = 0.5;
+const DEFAULT_COMBINE_MODE: 'max' | 'average' | 'min' = 'max';
+
+/**
+ * A filter strategy that boosts scores for high-utility content.
+ *
+ * Course authors assign priority weights to tags. Cards with high-priority
+ * tags get boosted scores, making them more likely to be presented first.
+ * This allows teaching the most useful, well-behaved concepts before
+ * moving on to rarer or more irregular ones.
+ *
+ * Example: When teaching phonics, prioritize common letters (s, t, a) over
+ * rare ones (x, z, q) by assigning higher priority weights to common letters.
+ *
+ * Implements CardFilter for use in Pipeline architecture.
+ * Also extends ContentNavigator for backward compatibility.
+ */
+export default class RelativePriorityNavigator extends ContentNavigator implements CardFilter {
+  private config: RelativePriorityConfig;
+  private _strategyData: ContentNavigationStrategyData;
+
+  /** Human-readable name for CardFilter interface */
+  name: string;
+
+  constructor(
+    user: UserDBInterface,
+    course: CourseDBInterface,
+    _strategyData: ContentNavigationStrategyData
+  ) {
+    super(user, course, _strategyData);
+    this._strategyData = _strategyData;
+    this.config = this.parseConfig(_strategyData.serializedData);
+    this.name = _strategyData.name || 'Relative Priority';
+  }
+
+  private parseConfig(serializedData: string): RelativePriorityConfig {
+    try {
+      const parsed = JSON.parse(serializedData);
+      return {
+        tagPriorities: parsed.tagPriorities || {},
+        defaultPriority: parsed.defaultPriority ?? DEFAULT_PRIORITY,
+        combineMode: parsed.combineMode ?? DEFAULT_COMBINE_MODE,
+        priorityInfluence: parsed.priorityInfluence ?? DEFAULT_PRIORITY_INFLUENCE,
+      };
+    } catch {
+      // Return safe defaults if parsing fails
+      return {
+        tagPriorities: {},
+        defaultPriority: DEFAULT_PRIORITY,
+        combineMode: DEFAULT_COMBINE_MODE,
+        priorityInfluence: DEFAULT_PRIORITY_INFLUENCE,
+      };
+    }
+  }
+
+  /**
+   * Look up the priority for a tag.
+   */
+  private getTagPriority(tagId: string): number {
+    return this.config.tagPriorities[tagId] ?? this.config.defaultPriority ?? DEFAULT_PRIORITY;
+  }
+
+  /**
+   * Compute combined priority for a card based on its tags.
+   */
+  private computeCardPriority(cardTags: string[]): number {
+    if (cardTags.length === 0) {
+      return this.config.defaultPriority ?? DEFAULT_PRIORITY;
+    }
+
+    const priorities = cardTags.map((tag) => this.getTagPriority(tag));
+
+    switch (this.config.combineMode) {
+      case 'max':
+        return Math.max(...priorities);
+      case 'min':
+        return Math.min(...priorities);
+      case 'average':
+        return priorities.reduce((sum, p) => sum + p, 0) / priorities.length;
+      default:
+        return Math.max(...priorities);
+    }
+  }
+
+  /**
+   * Compute boost factor based on priority.
+   *
+   * The formula: 1 + (priority - 0.5) * priorityInfluence
+   *
+   * This creates a multiplier centered around 1.0:
+   * - Priority 1.0 with influence 0.5 → 1.25 (25% boost)
+   * - Priority 0.5 with any influence → 1.00 (neutral)
+   * - Priority 0.0 with influence 0.5 → 0.75 (25% reduction)
+   */
+  private computeBoostFactor(priority: number): number {
+    const influence = this.config.priorityInfluence ?? DEFAULT_PRIORITY_INFLUENCE;
+    return 1 + (priority - 0.5) * influence;
+  }
+
+  /**
+   * Build human-readable reason for priority adjustment.
+   */
+  private buildPriorityReason(
+    cardTags: string[],
+    priority: number,
+    boostFactor: number,
+    finalScore: number
+  ): string {
+    if (cardTags.length === 0) {
+      return `No tags, neutral priority (${priority.toFixed(2)})`;
+    }
+
+    const tagList = cardTags.slice(0, 3).join(', ');
+    const more = cardTags.length > 3 ? ` (+${cardTags.length - 3} more)` : '';
+
+    if (boostFactor === 1.0) {
+      return `Neutral priority (${priority.toFixed(2)}) for tags: ${tagList}${more}`;
+    } else if (boostFactor > 1.0) {
+      return `High-priority tags: ${tagList}${more} (priority ${priority.toFixed(2)} → boost ${boostFactor.toFixed(2)}x → ${finalScore.toFixed(2)})`;
+    } else {
+      return `Low-priority tags: ${tagList}${more} (priority ${priority.toFixed(2)} → reduce ${boostFactor.toFixed(2)}x → ${finalScore.toFixed(2)})`;
+    }
+  }
+
+  /**
+   * Get tags for a single card.
+   */
+  private async getCardTags(cardId: string, course: CourseDBInterface): Promise<string[]> {
+    try {
+      const tagResponse = await course.getAppliedTags(cardId);
+      return tagResponse.rows.map((r) => r.doc?.name).filter((x): x is string => !!x);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * CardFilter.transform implementation.
+   *
+   * Apply priority-adjusted scoring. Cards with high-priority tags get boosted,
+   * cards with low-priority tags get reduced scores.
+   */
+  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+    const adjusted: WeightedCard[] = await Promise.all(
+      cards.map(async (card) => {
+        const cardTags = await this.getCardTags(card.cardId, context.course);
+        const priority = this.computeCardPriority(cardTags);
+        const boostFactor = this.computeBoostFactor(priority);
+        const finalScore = Math.max(0, Math.min(1, card.score * boostFactor));
+
+        // Determine action based on boost factor
+        const action = boostFactor > 1.0 ? 'boosted' : boostFactor < 1.0 ? 'penalized' : 'passed';
+
+        // Build reason explaining priority adjustment
+        const reason = this.buildPriorityReason(cardTags, priority, boostFactor, finalScore);
+
+        return {
+          ...card,
+          score: finalScore,
+          provenance: [
+            ...card.provenance,
+            {
+              strategy: 'relativePriority',
+              strategyName: this.strategyName || this.name,
+              strategyId: this.strategyId || 'NAVIGATION_STRATEGY-priority',
+              action,
+              score: finalScore,
+              reason,
+            },
+          ],
+        };
+      })
+    );
+
+    return adjusted;
+  }
+
+  /**
+   * Legacy getWeightedCards - now throws as filters should not be used as generators.
+   *
+   * Use transform() via Pipeline instead.
+   */
+  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+    throw new Error(
+      'RelativePriorityNavigator is a filter and should not be used as a generator. ' +
+        'Use Pipeline with a generator and this filter via transform().'
+    );
+  }
+
+  // Legacy methods - stub implementations since filters don't generate cards
+
+  async getNewCards(_n?: number): Promise<StudySessionNewItem[]> {
+    return [];
+  }
+
+  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
+    return [];
+  }
+}