@vue-skuilder/db 0.1.17 → 0.1.20

package/src/core/navigators/inferredPreference.ts

@@ -0,0 +1,107 @@
+// ============================================================================
+// INFERRED PREFERENCE NAVIGATOR — STUB
+// ============================================================================
+//
+// STATUS: NOT IMPLEMENTED — This file documents architectural intent only.
+//
+// ============================================================================
+//
+// ## Purpose
+//
+// Inferred preferences are learned from user behavior, as opposed to explicit
+// preferences which are configured via UI. The system observes patterns in
+// user interactions and adjusts card selection accordingly.
+//
+// ## Inference Signals
+//
+// Potential signals to learn from:
+//
+// 1. **Card dismissal patterns**: User consistently skips certain card types
+// 2. **Time-on-card**: User spends less time on certain content (boredom?)
+// 3. **Error patterns**: User struggles with certain presentation styles
+// 4. **Session timing**: User performs better at certain times of day
+// 5. **Tag success rates**: User masters some tags faster than others
+//
+// ## Inferred State (Proposed)
+//
+// ```typescript
+// interface InferredPreferenceState {
+//   // Learned tag affinities (positive = user does well, negative = struggles)
+//   tagAffinities: Record<string, number>;
+//
+//   // Presentation style preferences
+//   preferredStyles: {
+//     visualVsText: number;     // -1 to 1 (negative = text, positive = visual)
+//     shortVsLong: number;      // -1 to 1 (negative = long, positive = short)
+//   };
+//
+//   // Temporal patterns
+//   optimalSessionLength: number;  // minutes
+//   optimalTimeOfDay: number;      // hour (0-23)
+//
+//   // Confidence in inferences
+//   sampleSize: number;
+//   lastUpdated: string;
+// }
+// ```
+//
+// ## Relationship to Explicit Preferences
+//
+// - Explicit preferences (UserTagPreferenceFilter) always take precedence
+// - Inferred preferences act as soft suggestions when no explicit pref exists
+// - User can "lock in" an inference as an explicit preference via UI
+// - User can dismiss/override an inference ("I actually like text cards")
+//
+// ## Transparency Requirements
+//
+// Inferred preferences must be:
+//
+// 1. **Visible**: User can see what the system has inferred
+// 2. **Explainable**: "We noticed you master visual cards faster"
+// 3. **Overridable**: User can disable or invert any inference
+// 4. **Forgettable**: User can reset inferences and start fresh
+//
+// ## Implementation Considerations
+//
+// 1. **Cold start**: Need minimum sample size before inferring
+// 2. **Drift**: Preferences may change over time; use decay/recency weighting
+// 3. **Privacy**: Inference data is personal; handle with care
+// 4. **Bias**: Avoid reinforcing accidental patterns as permanent preferences
+//
+// ## Related Files
+//
+// - `filters/userTagPreference.ts` — Explicit preferences (takes precedence)
+// - `userGoal.ts` — Goals (destination, not path)
+// - `../types/strategyState.ts` — Storage mechanism
+//
+// ## Next Steps
+//
+// 1. Define minimum viable inference signals
+// 2. Design inference algorithms (simple heuristics vs ML)
+// 3. Build transparency UI ("Here's what we learned about you")
+// 4. Implement override/dismiss mechanism
+// 5. Add to card record collection for inference input
+//
+// ============================================================================
+
+// Placeholder export to make this a valid module
+export const INFERRED_PREFERENCE_NAVIGATOR_STUB = true;
+
+/**
+ * @stub InferredPreferenceNavigator
+ *
+ * A navigator that learns user preferences from behavior patterns.
+ * See module-level documentation for architectural intent.
+ *
+ * NOT IMPLEMENTED — This is a design placeholder.
+ */
+export interface InferredPreferenceState {
+  /** Learned affinity scores per tag (-1 to 1) */
+  tagAffinities: Record<string, number>;
+
+  /** Number of card interactions used to build inferences */
+  sampleSize: number;
+
+  /** ISO timestamp of last inference update */
+  updatedAt: string;
+}

package/src/core/navigators/interferenceMitigator.ts

@@ -0,0 +1,355 @@
+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;
+  }
+
+  /**
+   * 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 = card.tags ?? [];
+      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 [];
+  }
+}