@vue-skuilder/db 0.1.17 → 0.1.20

package/src/core/navigators/filters/userTagPreference.ts

@@ -0,0 +1,232 @@
+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 './types';
+
+// ============================================================================
+// USER TAG PREFERENCE FILTER
+// ============================================================================
+//
+// Allows users to personalize their learning experience by specifying:
+// - Tags to boost/penalize (score multiplied by boost factor)
+//
+// User preferences are stored in STRATEGY_STATE documents in the user's
+// database, enabling persistence across sessions and sync across devices.
+//
+// Use cases:
+// - Goal-based learning: "I want to learn piano by ear, skip sight-reading"
+// - Selective focus: "I only want to practice chess endgames"
+// - Accessibility: "Skip text-heavy cards, prefer visual content"
+// - Difficulty customization: "Skip beginner content I already know"
+//
+// ============================================================================
+
+/**
+ * User's tag preference state, stored in STRATEGY_STATE document.
+ *
+ * This interface defines what gets persisted to the user's database.
+ * UI components write to this structure, and the filter reads from it.
+ *
+ * ## Preferences vs Goals
+ *
+ * Preferences are **path constraints** — they affect HOW the user learns,
+ * not WHAT they're trying to learn. Examples:
+ * - "Skip text-heavy cards" (accessibility)
+ * - "Prefer visual content"
+ *
+ * For **goal-based** filtering (defining WHAT to learn), see the separate
+ * UserGoalNavigator (stub). Goals affect progress tracking and completion
+ * criteria; preferences only affect card selection.
+ *
+ * ## Slider Semantics
+ *
+ * Each tag maps to a multiplier value in the `boost` record:
+ * - `0` = banish/exclude (card score = 0)
+ * - `0.5` = penalize by 50%
+ * - `1.0` = neutral/no effect (default when tag added)
+ * - `2.0` = 2x preference boost
+ * - Higher values = stronger preference
+ *
+ * If multiple tags on a card have preferences, the maximum multiplier wins.
+ */
+export interface UserTagPreferenceState {
+  /**
+   * Tag-specific multipliers.
+   * Maps tag name to score multiplier (0 = exclude, 1 = neutral, >1 = boost).
+   */
+  boost: Record<string, number>;
+
+  /**
+   * ISO timestamp of last update.
+   * Use `moment.utc(updatedAt)` to parse into a Moment object.
+   */
+  updatedAt: string;
+}
+
+/**
+ * A filter that applies user-configured tag preferences.
+ *
+ * Reads preferences from STRATEGY_STATE document in user's database.
+ * If no preferences exist, passes through unchanged (no-op).
+ *
+ * Implements CardFilter for use in Pipeline architecture.
+ * Also extends ContentNavigator for compatibility with dynamic loading.
+ */
+export default class UserTagPreferenceFilter extends ContentNavigator implements CardFilter {
+  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.name = strategyData.name || 'User Tag Preferences';
+  }
+
+  /**
+   * Compute multiplier for a card based on its tags and user preferences.
+   * Returns the maximum multiplier among all matching tags, or 1.0 if no matches.
+   */
+  private computeMultiplier(cardTags: string[], boostMap: Record<string, number>): number {
+    const multipliers = cardTags
+      .map((tag) => boostMap[tag])
+      .filter((val) => val !== undefined);
+
+    if (multipliers.length === 0) {
+      return 1.0;
+    }
+
+    // Use max multiplier among matching tags
+    return Math.max(...multipliers);
+  }
+
+  /**
+   * Build human-readable reason for the filter's decision.
+   */
+  private buildReason(
+    cardTags: string[],
+    boostMap: Record<string, number>,
+    multiplier: number
+  ): string {
+    // Find which tag(s) contributed to the multiplier
+    const matchingTags = cardTags.filter((tag) => boostMap[tag] === multiplier);
+
+    if (multiplier === 0) {
+      return `Excluded by user preference: ${matchingTags.join(', ')} (${multiplier}x)`;
+    }
+
+    if (multiplier < 1.0) {
+      return `Penalized by user preference: ${matchingTags.join(', ')} (${multiplier.toFixed(2)}x)`;
+    }
+
+    if (multiplier > 1.0) {
+      return `Boosted by user preference: ${matchingTags.join(', ')} (${multiplier.toFixed(2)}x)`;
+    }
+
+    return 'No matching user preferences';
+  }
+
+  /**
+   * CardFilter.transform implementation.
+   *
+   * Apply user tag preferences:
+   * 1. Read preferences from strategy state
+   * 2. If no preferences, pass through unchanged
+   * 3. For each card:
+   *    - Look up tag in boost record
+   *    - If tag found: apply multiplier (0 = exclude, 1 = neutral, >1 = boost)
+   *    - If multiple tags match: use max multiplier
+   *    - Append provenance with clear reason
+   */
+  async transform(cards: WeightedCard[], _context: FilterContext): Promise<WeightedCard[]> {
+    // Read user preferences from strategy state
+    const prefs = await this.getStrategyState<UserTagPreferenceState>();
+    
+
+    // No preferences configured → pass through unchanged
+    if (!prefs || Object.keys(prefs.boost).length === 0) {
+      return cards.map((card) => ({
+        ...card,
+        provenance: [
+          ...card.provenance,
+          {
+            strategy: 'userTagPreference',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || this._strategyData._id,
+            action: 'passed' as const,
+            score: card.score,
+            reason: 'No user tag preferences configured',
+          },
+        ],
+      }));
+    }
+
+    // Process each card
+    const adjusted: WeightedCard[] = await Promise.all(
+      cards.map(async (card) => {
+        const cardTags = card.tags ?? [];
+
+        // Compute multiplier based on card tags and user preferences
+        const multiplier = this.computeMultiplier(cardTags, prefs.boost);
+        const finalScore = Math.min(1, card.score * multiplier);
+
+        // Determine action for provenance
+        let action: 'passed' | 'boosted' | 'penalized';
+        if (multiplier === 0 || multiplier < 1.0) {
+          action = 'penalized';
+        } else if (multiplier > 1.0) {
+          action = 'boosted';
+        } else {
+          action = 'passed';
+        }
+
+        return {
+          ...card,
+          score: finalScore,
+          provenance: [
+            ...card.provenance,
+            {
+              strategy: 'userTagPreference',
+              strategyName: this.strategyName || this.name,
+              strategyId: this.strategyId || this._strategyData._id,
+              action,
+              score: finalScore,
+              reason: this.buildReason(cardTags, prefs.boost, multiplier),
+            },
+          ],
+        };
+      })
+    );
+
+    return adjusted;
+  }
+
+  /**
+   * Legacy getWeightedCards - throws as filters should not be used as generators.
+   */
+  async getWeightedCards(_limit: number): Promise<WeightedCard[]> {
+    throw new Error(
+      'UserTagPreferenceFilter 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/generators/index.ts

@@ -0,0 +1,2 @@
+// Generator types and interfaces
+export type { CardGenerator, GeneratorContext, CardGeneratorFactory } from './types';

package/src/core/navigators/generators/types.ts

@@ -0,0 +1,107 @@
+import type { WeightedCard } from '../index';
+import type { CourseDBInterface } from '../../interfaces/courseDB';
+import type { UserDBInterface } from '../../interfaces/userDB';
+
+// ============================================================================
+// CARD GENERATOR INTERFACE
+// ============================================================================
+//
+// Generators produce candidate cards with initial scores.
+// They are the "source" stage of a navigation pipeline.
+//
+// Examples: ELO (skill proximity), SRS (review scheduling), HardcodedOrder
+//
+// Generators differ from filters:
+// - Generators: produce candidates from DB queries, assign initial scores
+// - Filters: transform existing candidates, adjust scores with multipliers
+//
+// The Pipeline class orchestrates: Generator → Filter₁ → Filter₂ → ... → Results
+//
+// ============================================================================
+
+/**
+ * Context available to generators when producing candidates.
+ *
+ * Built once per getWeightedCards() call by the Pipeline.
+ */
+export interface GeneratorContext {
+  /** User database interface */
+  user: UserDBInterface;
+
+  /** Course database interface */
+  course: CourseDBInterface;
+
+  /** User's global ELO score for this course */
+  userElo: number;
+
+  // Future extensions:
+  // - user's tag-level ELO data
+  // - course config
+  // - session state (cards already seen this session)
+}
+
+/**
+ * A generator that produces candidate cards with initial scores.
+ *
+ * Generators are the "source" stage of a navigation pipeline.
+ * They query the database for eligible cards and assign initial
+ * suitability scores based on their strategy (ELO proximity,
+ * review urgency, fixed order, etc.).
+ *
+ * ## Implementation Guidelines
+ *
+ * 1. **Create provenance**: Each card should have a provenance entry
+ *    with action='generated' documenting why it was selected.
+ *
+ * 2. **Score semantics**: Higher scores = more suitable for presentation.
+ *    Scores should be in [0, 1] range for composability.
+ *
+ * 3. **Limit handling**: Respect the limit parameter, but may over-fetch
+ *    internally if needed for scoring accuracy.
+ *
+ * 4. **Sort before returning**: Return cards sorted by score descending.
+ *
+ * ## Example Implementation
+ *
+ * ```typescript
+ * const myGenerator: CardGenerator = {
+ *   name: 'My Generator',
+ *   async getWeightedCards(limit, context) {
+ *     const candidates = await fetchCandidates(context.course, limit);
+ *     return candidates.map(c => ({
+ *       cardId: c.id,
+ *       courseId: context.course.getCourseID(),
+ *       score: computeScore(c, context),
+ *       provenance: [{
+ *         strategy: 'myGenerator',
+ *         strategyName: 'My Generator',
+ *         strategyId: 'MY_GENERATOR',
+ *         action: 'generated',
+ *         score: computeScore(c, context),
+ *         reason: 'Explanation of selection'
+ *       }]
+ *     }));
+ *   }
+ * };
+ * ```
+ */
+export interface CardGenerator {
+  /** Human-readable name for this generator */
+  name: string;
+
+  /**
+   * Produce candidate cards with initial scores.
+   *
+   * @param limit - Maximum number of cards to return
+   * @param context - Shared context (user, course, userElo, etc.)
+   * @returns Cards sorted by score descending, with provenance
+   */
+  getWeightedCards(limit: number, context: GeneratorContext): Promise<WeightedCard[]>;
+}
+
+/**
+ * Factory function type for creating generators from configuration.
+ *
+ * Used by PipelineAssembler to instantiate generators from strategy documents.
+ */
+export type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;

package/src/core/navigators/hardcodedOrder.ts

@@ -1,22 +1,55 @@
-import { CourseDBInterface, QualifiedCardID, StudySessionNewItem, StudySessionReviewItem, UserDBInterface } from '..';
-import { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
-import { ScheduledCard } from '../types/user';
+import type {
+  CourseDBInterface,
+  QualifiedCardID,
+  StudySessionNewItem,
+  StudySessionReviewItem,
+  UserDBInterface,
+} from '..';
+import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+import type { ScheduledCard } from '../types/user';
 import { ContentNavigator } from './index';
+import type { WeightedCard } from './index';
+import type { CardGenerator, GeneratorContext } from './generators/types';
 import { logger } from '../../util/logger';
 
-export default class HardcodedOrderNavigator extends ContentNavigator {
+// ============================================================================
+// HARDCODED ORDER NAVIGATOR
+// ============================================================================
+//
+// A generator strategy that presents cards in a fixed, author-defined order.
+//
+// Use case: When course authors want explicit control over content sequencing,
+// e.g., teaching letters in a specific pedagogical order.
+//
+// The order is defined in serializedData as a JSON array of card IDs.
+// Earlier positions in the array get higher scores.
+//
+// ============================================================================
+
+/**
+ * A navigation strategy that presents cards in a fixed order.
+ *
+ * Implements CardGenerator for use in Pipeline architecture.
+ * Also extends ContentNavigator for backward compatibility with legacy code.
+ *
+ * Scoring:
+ * - Earlier cards in the sequence get higher scores
+ * - Reviews get score 1.0 (highest priority)
+ * - New cards scored by position: 1.0 - (position / total) * 0.5
+ */
+export default class HardcodedOrderNavigator extends ContentNavigator implements CardGenerator {
+  /** Human-readable name for CardGenerator interface */
+  name: string;
+
   private orderedCardIds: string[] = [];
-  private user: UserDBInterface;
-  private course: CourseDBInterface;
 
   constructor(
     user: UserDBInterface,
     course: CourseDBInterface,
     strategyData: ContentNavigationStrategyData
   ) {
-    super();
-    this.user = user;
-    this.course = course;
+    super(user, course, strategyData);
+    this.name = strategyData.name || 'Hardcoded Order';
 
     if (strategyData.serializedData) {
       try {
@@ -45,9 +78,7 @@ export default class HardcodedOrderNavigator extends ContentNavigator {
   async getNewCards(limit: number = 99): Promise<StudySessionNewItem[]> {
     const activeCardIds = (await this.user.getActiveCards()).map((c: QualifiedCardID) => c.cardID);
 
-    const newCardIds = this.orderedCardIds.filter(
-      (cardId) => !activeCardIds.includes(cardId)
-    );
+    const newCardIds = this.orderedCardIds.filter((cardId) => !activeCardIds.includes(cardId));
 
     const cardsToReturn = newCardIds.slice(0, limit);
 
@@ -61,4 +92,72 @@ export default class HardcodedOrderNavigator extends ContentNavigator {
       };
     });
   }
+
+  /**
+   * Get cards in hardcoded order with scores based on position.
+   *
+   * Earlier cards in the sequence get higher scores.
+   * Score formula: 1.0 - (position / totalCards) * 0.5
+   * This ensures scores range from 1.0 (first card) to 0.5+ (last card).
+   *
+   * This method supports both the legacy signature (limit only) and the
+   * CardGenerator interface signature (limit, context).
+   *
+   * @param limit - Maximum number of cards to return
+   * @param _context - Optional GeneratorContext (currently unused, but required for interface)
+   */
+  async getWeightedCards(limit: number, _context?: GeneratorContext): Promise<WeightedCard[]> {
+    const activeCardIds = (await this.user.getActiveCards()).map((c: QualifiedCardID) => c.cardID);
+    const reviews = await this.getPendingReviews();
+
+    // Filter out already-active cards
+    const newCardIds = this.orderedCardIds.filter((cardId) => !activeCardIds.includes(cardId));
+
+    const totalCards = newCardIds.length;
+
+    // Score new cards by position in sequence
+    const scoredNew: WeightedCard[] = newCardIds.slice(0, limit).map((cardId, index) => {
+      const position = index + 1;
+      const score = Math.max(0.5, 1.0 - (index / totalCards) * 0.5);
+
+      return {
+        cardId,
+        courseId: this.course.getCourseID(),
+        score,
+        provenance: [
+          {
+            strategy: 'hardcodedOrder',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || 'NAVIGATION_STRATEGY-hardcoded',
+            action: 'generated',
+            score,
+            reason: `Position ${position} of ${totalCards} in fixed sequence, new card`,
+          },
+        ],
+      };
+    });
+
+    // Score reviews at 1.0 (highest priority)
+    const scoredReviews: WeightedCard[] = reviews.map((r) => ({
+      cardId: r.cardID,
+      courseId: r.courseID,
+      score: 1.0,
+      provenance: [
+        {
+          strategy: 'hardcodedOrder',
+          strategyName: this.strategyName || this.name,
+          strategyId: this.strategyId || 'NAVIGATION_STRATEGY-hardcoded',
+          action: 'generated',
+          score: 1.0,
+          reason: 'Scheduled review, highest priority',
+        },
+      ],
+    }));
+
+    // Combine (reviews already sorted at top due to score=1.0)
+    const all = [...scoredReviews, ...scoredNew];
+    all.sort((a, b) => b.score - a.score);
+
+    return all.slice(0, limit);
+  }
 }