@vue-skuilder/db 0.1.16 → 0.1.18

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);
+  }
 }

package/src/core/navigators/hierarchyDefinition.ts

@@ -0,0 +1,266 @@
+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';
+
+/**
+ * A single prerequisite requirement for a tag.
+ * Each prerequisite refers to one tag with its own mastery threshold.
+ */
+interface TagPrerequisite {
+  /** The tag that must be mastered */
+  tag: string;
+  /** Thresholds for considering this prerequisite tag "mastered" */
+  masteryThreshold?: {
+    /** Minimum ELO score for mastery. If not set, uses avgElo comparison */
+    minElo?: number;
+    /** Minimum interaction count (default: 3) */
+    minCount?: number;
+  };
+}
+
+/**
+ * Configuration for the HierarchyDefinition strategy
+ */
+export interface HierarchyConfig {
+  /** Map of tag ID to its list of prerequisites (each with individual thresholds) */
+  prerequisites: {
+    [tagId: string]: TagPrerequisite[];
+  };
+}
+
+const DEFAULT_MIN_COUNT = 3;
+
+/**
+ * A filter strategy that gates cards based on prerequisite mastery.
+ *
+ * Cards are locked until the user masters all prerequisite tags.
+ * Locked cards receive score: 0 (hard filter).
+ *
+ * Mastery is determined by:
+ * - User's ELO for the tag exceeds threshold (or avgElo if not specified)
+ * - User has minimum interaction count with the tag
+ *
+ * Tags with no prerequisites are always unlocked.
+ *
+ * Implements CardFilter for use in Pipeline architecture.
+ * Also extends ContentNavigator for backward compatibility.
+ */
+export default class HierarchyDefinitionNavigator extends ContentNavigator implements CardFilter {
+  private config: HierarchyConfig;
+  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 || 'Hierarchy Definition';
+  }
+
+  private parseConfig(serializedData: string): HierarchyConfig {
+    try {
+      const parsed = JSON.parse(serializedData);
+      return {
+        prerequisites: parsed.prerequisites || {},
+      };
+    } catch {
+      // Return safe defaults if parsing fails
+      return {
+        prerequisites: {},
+      };
+    }
+  }
+
+  /**
+   * Check if a specific prerequisite is satisfied
+   */
+  private isPrerequisiteMet(
+    prereq: TagPrerequisite,
+    userTagElo: { score: number; count: number } | undefined,
+    userGlobalElo: number
+  ): boolean {
+    if (!userTagElo) return false;
+
+    const minCount = prereq.masteryThreshold?.minCount ?? DEFAULT_MIN_COUNT;
+    if (userTagElo.count < minCount) return false;
+
+    if (prereq.masteryThreshold?.minElo !== undefined) {
+      return userTagElo.score >= prereq.masteryThreshold.minElo;
+    } else {
+      // Default: user ELO for tag > global user ELO (proxy for "above average")
+      return userTagElo.score >= userGlobalElo;
+    }
+  }
+
+  /**
+   * Get the set of tags the user has mastered.
+   * A tag is "mastered" if it appears as a prerequisite somewhere and meets its threshold.
+   */
+  private async getMasteredTags(context: FilterContext): Promise<Set<string>> {
+    const mastered = new Set<string>();
+
+    try {
+      const courseReg = await context.user.getCourseRegDoc(context.course.getCourseID());
+      const userElo = toCourseElo(courseReg.elo);
+
+      // Collect all unique prerequisite tags and check mastery for each
+      for (const prereqs of Object.values(this.config.prerequisites)) {
+        for (const prereq of prereqs) {
+          const tagElo = userElo.tags[prereq.tag];
+          if (this.isPrerequisiteMet(prereq, tagElo, userElo.global.score)) {
+            mastered.add(prereq.tag);
+          }
+        }
+      }
+    } catch {
+      // If we can't get user data, return empty set (no tags mastered)
+    }
+
+    return mastered;
+  }
+
+  /**
+   * Get the set of tags that are unlocked (prerequisites met)
+   */
+  private getUnlockedTags(masteredTags: Set<string>): Set<string> {
+    const unlocked = new Set<string>();
+
+    for (const [tagId, prereqs] of Object.entries(this.config.prerequisites)) {
+      const allPrereqsMet = prereqs.every((prereq) => masteredTags.has(prereq.tag));
+      if (allPrereqsMet) {
+        unlocked.add(tagId);
+      }
+    }
+
+    return unlocked;
+  }
+
+  /**
+   * Check if a tag has prerequisites defined in config
+   */
+  private hasPrerequisites(tagId: string): boolean {
+    return tagId in this.config.prerequisites;
+  }
+
+  /**
+   * Check if a card is unlocked and generate reason.
+   */
+  private async checkCardUnlock(
+    cardId: string,
+    course: CourseDBInterface,
+    unlockedTags: Set<string>,
+    masteredTags: Set<string>
+  ): Promise<{ isUnlocked: boolean; reason: string }> {
+    try {
+      const tagResponse = await course.getAppliedTags(cardId);
+      const cardTags = tagResponse.rows.map((row) => row.value?.name || row.key);
+
+      // Check each tag's prerequisite status
+      const lockedTags = cardTags.filter(
+        (tag) => this.hasPrerequisites(tag) && !unlockedTags.has(tag)
+      );
+
+      if (lockedTags.length === 0) {
+        const tagList = cardTags.length > 0 ? cardTags.join(', ') : 'none';
+        return {
+          isUnlocked: true,
+          reason: `Prerequisites met, tags: ${tagList}`,
+        };
+      }
+
+      // Find missing prerequisites for locked tags
+      const missingPrereqs = lockedTags.flatMap((tag) => {
+        const prereqs = this.config.prerequisites[tag] || [];
+        return prereqs.filter((p) => !masteredTags.has(p.tag)).map((p) => p.tag);
+      });
+
+      return {
+        isUnlocked: false,
+        reason: `Blocked: missing prerequisites ${missingPrereqs.join(', ')} for tags ${lockedTags.join(', ')}`,
+      };
+    } catch {
+      // If we can't get tags, assume unlocked (fail open)
+      return {
+        isUnlocked: true,
+        reason: 'Prerequisites check skipped (tag lookup failed)',
+      };
+    }
+  }
+
+  /**
+   * CardFilter.transform implementation.
+   *
+   * Apply prerequisite gating to cards. Cards with locked tags receive score: 0.
+   */
+  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+    // Get mastery state
+    const masteredTags = await this.getMasteredTags(context);
+    const unlockedTags = this.getUnlockedTags(masteredTags);
+
+    // Apply prerequisite gating as score multiplier
+    const gated: WeightedCard[] = [];
+
+    for (const card of cards) {
+      const { isUnlocked, reason } = await this.checkCardUnlock(
+        card.cardId,
+        context.course,
+        unlockedTags,
+        masteredTags
+      );
+      const finalScore = isUnlocked ? card.score : 0;
+      const action = isUnlocked ? 'passed' : 'penalized';
+
+      gated.push({
+        ...card,
+        score: finalScore,
+        provenance: [
+          ...card.provenance,
+          {
+            strategy: 'hierarchyDefinition',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || 'NAVIGATION_STRATEGY-hierarchy',
+            action,
+            score: finalScore,
+            reason,
+          },
+        ],
+      });
+    }
+
+    return gated;
+  }
+
+  /**
+   * 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(
+      'HierarchyDefinitionNavigator 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 [];
+  }
+}