@vue-skuilder/db 0.1.16 → 0.1.18

package/src/core/navigators/PipelineAssembler.ts

@@ -0,0 +1,194 @@
+import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+import { ContentNavigator, isGenerator, isFilter, Navigators } from './index';
+import type { CardFilter } from './filters/types';
+import type { CardGenerator } from './generators/types';
+import { Pipeline } from './Pipeline';
+import { DocType } from '../types/types-legacy';
+import { logger } from '../../util/logger';
+import type { CourseDBInterface } from '../interfaces/courseDB';
+import type { UserDBInterface } from '../interfaces/userDB';
+import CompositeGenerator from './CompositeGenerator';
+
+// ============================================================================
+// PIPELINE ASSEMBLER
+// ============================================================================
+//
+// Assembles navigation strategies into a Pipeline instance.
+//
+// This class is DB-agnostic: it receives strategy documents and returns an
+// assembled, ready-to-use Pipeline. This separation enables:
+// 1. Use with different DB implementations (Couch, Static, etc.)
+// 2. Future dynamic/evolutionary strategy selection
+// 3. Easy unit testing without DB mocking
+//
+// Pipeline assembly:
+// 1. Separate strategies into generators and filters by role
+// 2. Instantiate generator(s) - wrap multiple in CompositeGenerator
+// 3. Instantiate filters
+// 4. Return Pipeline(generator, filters)
+//
+// ============================================================================
+
+/**
+ * Input for pipeline assembly.
+ */
+export interface PipelineAssemblerInput {
+  /** All strategy documents to assemble into a pipeline */
+  strategies: ContentNavigationStrategyData[];
+  /** User database interface (required for instantiation) */
+  user: UserDBInterface;
+  /** Course database interface (required for instantiation) */
+  course: CourseDBInterface;
+}
+
+/**
+ * Result of pipeline assembly.
+ */
+export interface PipelineAssemblyResult {
+  /** The assembled pipeline, or null if assembly failed */
+  pipeline: Pipeline | null;
+  /** Generator strategies found (for informational purposes) */
+  generatorStrategies: ContentNavigationStrategyData[];
+  /** Filter strategies found (for informational purposes) */
+  filterStrategies: ContentNavigationStrategyData[];
+  /** Warnings encountered during assembly (logged but non-fatal) */
+  warnings: string[];
+}
+
+/**
+ * Assembles navigation strategies into a Pipeline.
+ *
+ * Instantiates generators and filters from strategy documents and
+ * composes them into a ready-to-use Pipeline instance.
+ */
+export class PipelineAssembler {
+  /**
+   * Assembles a navigation pipeline from strategy documents.
+   *
+   * 1. Separates into generators and filters by role
+   * 2. Validates at least one generator exists (or creates default ELO)
+   * 3. Instantiates generators - wraps multiple in CompositeGenerator
+   * 4. Instantiates filters
+   * 5. Returns Pipeline(generator, filters)
+   *
+   * @param input - Strategy documents plus user/course interfaces
+   * @returns Assembled pipeline and any warnings
+   */
+  async assemble(input: PipelineAssemblerInput): Promise<PipelineAssemblyResult> {
+    const { strategies, user, course } = input;
+    const warnings: string[] = [];
+
+    if (strategies.length === 0) {
+      return {
+        pipeline: null,
+        generatorStrategies: [],
+        filterStrategies: [],
+        warnings,
+      };
+    }
+
+    // Separate generators from filters
+    const generatorStrategies: ContentNavigationStrategyData[] = [];
+    const filterStrategies: ContentNavigationStrategyData[] = [];
+
+    for (const s of strategies) {
+      if (isGenerator(s.implementingClass)) {
+        generatorStrategies.push(s);
+      } else if (isFilter(s.implementingClass)) {
+        filterStrategies.push(s);
+      } else {
+        // Unknown strategy type — skip with warning
+        warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
+      }
+    }
+
+    // If no generator but filters exist, use default ELO generator
+    if (generatorStrategies.length === 0) {
+      if (filterStrategies.length > 0) {
+        logger.debug(
+          '[PipelineAssembler] No generator found, using default ELO with configured filters'
+        );
+        generatorStrategies.push(this.makeDefaultEloStrategy(course.getCourseID()));
+      } else {
+        warnings.push('No generator strategy found');
+        return {
+          pipeline: null,
+          generatorStrategies: [],
+          filterStrategies: [],
+          warnings,
+        };
+      }
+    }
+
+    // Instantiate generators
+    let generator: CardGenerator;
+
+    if (generatorStrategies.length === 1) {
+      // Single generator
+      const nav = await ContentNavigator.create(user, course, generatorStrategies[0]);
+      generator = nav as unknown as CardGenerator;
+      logger.debug(`[PipelineAssembler] Using single generator: ${generatorStrategies[0].name}`);
+    } else {
+      // Multiple generators - wrap in CompositeGenerator
+      logger.debug(
+        `[PipelineAssembler] Using CompositeGenerator for ${generatorStrategies.length} generators: ${generatorStrategies.map((g) => g.name).join(', ')}`
+      );
+      generator = await CompositeGenerator.fromStrategies(user, course, generatorStrategies);
+    }
+
+    // Instantiate filters
+    const filters: CardFilter[] = [];
+
+    // Sort filters alphabetically for deterministic ordering
+    const sortedFilterStrategies = [...filterStrategies].sort((a, b) =>
+      a.name.localeCompare(b.name)
+    );
+
+    for (const filterStrategy of sortedFilterStrategies) {
+      try {
+        const nav = await ContentNavigator.create(user, course, filterStrategy);
+        // The navigator implements CardFilter
+        if ('transform' in nav && typeof nav.transform === 'function') {
+          filters.push(nav as unknown as CardFilter);
+          logger.debug(`[PipelineAssembler] Added filter: ${filterStrategy.name}`);
+        } else {
+          warnings.push(
+            `Filter '${filterStrategy.name}' does not implement CardFilter.transform(), skipping`
+          );
+        }
+      } catch (e) {
+        warnings.push(`Failed to instantiate filter '${filterStrategy.name}': ${e}`);
+      }
+    }
+
+    // Build pipeline
+    const pipeline = new Pipeline(generator, filters, user, course);
+
+    logger.debug(
+      `[PipelineAssembler] Assembled pipeline with ${generatorStrategies.length} generator(s) and ${filters.length} filter(s)`
+    );
+
+    return {
+      pipeline,
+      generatorStrategies,
+      filterStrategies: sortedFilterStrategies,
+      warnings,
+    };
+  }
+
+  /**
+   * Creates a default ELO generator strategy.
+   * Used when filters are configured but no generator is specified.
+   */
+  private makeDefaultEloStrategy(courseId: string): ContentNavigationStrategyData {
+    return {
+      _id: 'NAVIGATION_STRATEGY-ELO-default',
+      course: courseId,
+      docType: DocType.NAVIGATION_STRATEGY,
+      name: 'ELO (default)',
+      description: 'Default ELO-based generator',
+      implementingClass: Navigators.ELO,
+      serializedData: '',
+    };
+  }
+}

package/src/core/navigators/elo.ts

@@ -1,27 +1,54 @@
-import { ScheduledCard } from '../types/user';
-import { CourseDBInterface } from '../interfaces/courseDB';
-import { UserDBInterface } from '../interfaces/userDB';
+import type { ScheduledCard } from '../types/user';
+import type { CourseDBInterface } from '../interfaces/courseDB';
+import type { UserDBInterface } from '../interfaces/userDB';
 import { ContentNavigator } from './index';
-import { CourseElo } from '@vue-skuilder/common';
-import { StudySessionReviewItem, StudySessionNewItem, QualifiedCardID } from '..';
+import type { WeightedCard } from './index';
+import type { CourseElo } from '@vue-skuilder/common';
+import { toCourseElo } from '@vue-skuilder/common';
+import type { StudySessionReviewItem, StudySessionNewItem, QualifiedCardID } from '..';
+import type { CardGenerator, GeneratorContext } from './generators/types';
 
-export default class ELONavigator extends ContentNavigator {
-  user: UserDBInterface;
-  course: CourseDBInterface;
+// ============================================================================
+// ELO NAVIGATOR
+// ============================================================================
+//
+// A generator strategy that selects new cards based on ELO proximity.
+//
+// Cards closer to the user's skill level (ELO) receive higher scores.
+// This ensures learners see content matched to their current ability.
+//
+// NOTE: This generator only handles NEW cards. Reviews are handled by
+// SRSNavigator. Use CompositeGenerator to combine both.
+//
+// ============================================================================
+
+/**
+ * A navigation strategy that scores new cards by ELO proximity.
+ *
+ * Implements CardGenerator for use in Pipeline architecture.
+ * Also extends ContentNavigator for backward compatibility with legacy code.
+ *
+ * Higher scores indicate better ELO match:
+ * - Cards at user's ELO level score highest
+ * - Score decreases with ELO distance
+ *
+ * Only returns new cards - use SRSNavigator for reviews.
+ */
+export default class ELONavigator extends ContentNavigator implements CardGenerator {
+  /** Human-readable name for CardGenerator interface */
+  name: string;
 
   constructor(
     user: UserDBInterface,
-    course: CourseDBInterface
+    course: CourseDBInterface,
+    strategyData?: { name: string; _id: string }
     // The ELO strategy is non-parameterized.
     //
     // It instead relies on existing meta data from the course and user with respect to
-    //
-    //
-    // strategy?: ContentNavigationStrategyData
+    // ELO scores - it uses those to select cards matched to user skill level.
   ) {
-    super();
-    this.user = user;
-    this.course = course;
+    super(user, course, strategyData as any);
+    this.name = strategyData?.name || 'ELO';
   }
 
   async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
@@ -76,4 +103,66 @@ export default class ELONavigator extends ContentNavigator {
       };
     });
   }
+
+  /**
+   * Get new cards with suitability scores based on ELO distance.
+   *
+   * Cards closer to user's ELO get higher scores.
+   * Score formula: max(0, 1 - distance / 500)
+   *
+   * NOTE: This generator only handles NEW cards. Reviews are handled by
+   * SRSNavigator. Use CompositeGenerator to combine both.
+   *
+   * 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 (used when called via Pipeline)
+   */
+  async getWeightedCards(limit: number, context?: GeneratorContext): Promise<WeightedCard[]> {
+    // Determine user ELO - from context if available, otherwise fetch
+    let userGlobalElo: number;
+    if (context?.userElo !== undefined) {
+      userGlobalElo = context.userElo;
+    } else {
+      const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
+      const userElo = toCourseElo(courseReg.elo);
+      userGlobalElo = userElo.global.score;
+    }
+
+    // Get new cards (existing logic)
+    const newCards = await this.getNewCards(limit);
+
+    // Get ELO data for all cards in one batch
+    const cardIds = newCards.map((c) => c.cardID);
+    const cardEloData = await this.course.getCardEloData(cardIds);
+
+    // Score new cards by ELO distance
+    const scored: WeightedCard[] = newCards.map((c, i) => {
+      const cardElo = cardEloData[i]?.global?.score ?? 1000;
+      const distance = Math.abs(cardElo - userGlobalElo);
+      const score = Math.max(0, 1 - distance / 500);
+
+      return {
+        cardId: c.cardID,
+        courseId: c.courseID,
+        score,
+        provenance: [
+          {
+            strategy: 'elo',
+            strategyName: this.strategyName || this.name,
+            strategyId: this.strategyId || 'NAVIGATION_STRATEGY-ELO-default',
+            action: 'generated',
+            score,
+            reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), new card`,
+          },
+        ],
+      };
+    });
+
+    // Sort by score descending
+    scored.sort((a, b) => b.score - a.score);
+
+    return scored.slice(0, limit);
+  }
 }

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

@@ -0,0 +1,132 @@
+import type { WeightedCard } from '../index';
+import type { CardFilter, FilterContext } from './types';
+
+// ============================================================================
+// ELO DISTANCE FILTER
+// ============================================================================
+//
+// Penalizes cards that are far from the user's current ELO using a smooth curve.
+//
+// This filter addresses cross-strategy coordination:
+// - SRS generates reviews based on scheduling
+// - But some scheduled cards may be "below" the user's current level
+// - Or "above" (shouldn't happen often, but possible)
+//
+// By applying ELO distance penalties, we can:
+// - Deprioritize reviews the user has "moved beyond"
+// - Deprioritize cards that are too hard for current skill level
+//
+// The penalty curve is smooth (no discontinuities) using a Gaussian-like decay.
+//
+// ============================================================================
+
+/**
+ * Configuration for the ELO distance filter.
+ */
+export interface EloDistanceConfig {
+  /**
+   * The ELO distance at which the multiplier is ~0.6 (one standard deviation).
+   * Default: 200 ELO points.
+   *
+   * - At distance 0: multiplier ≈ 1.0
+   * - At distance = halfLife: multiplier ≈ 0.6
+   * - At distance = 2 * halfLife: multiplier ≈ 0.37
+   * - At distance = 3 * halfLife: multiplier ≈ 0.22
+   */
+  halfLife?: number;
+
+  /**
+   * Minimum multiplier (floor) to prevent scores from going too low.
+   * Default: 0.3
+   */
+  minMultiplier?: number;
+
+  /**
+   * Maximum multiplier (ceiling). Usually 1.0 (no boost for close cards).
+   * Default: 1.0
+   */
+  maxMultiplier?: number;
+}
+
+const DEFAULT_HALF_LIFE = 200;
+const DEFAULT_MIN_MULTIPLIER = 0.3;
+const DEFAULT_MAX_MULTIPLIER = 1.0;
+
+/**
+ * Compute the multiplier for a given ELO distance using Gaussian decay.
+ *
+ * Formula: minMultiplier + (maxMultiplier - minMultiplier) * exp(-(distance/halfLife)^2)
+ *
+ * This produces a smooth bell curve centered at distance=0:
+ * - At distance 0: multiplier = maxMultiplier (1.0)
+ * - As distance increases: multiplier smoothly decays toward minMultiplier
+ * - No discontinuities or sudden jumps
+ */
+function computeMultiplier(
+  distance: number,
+  halfLife: number,
+  minMultiplier: number,
+  maxMultiplier: number
+): number {
+  // Gaussian decay: exp(-(d/h)^2)
+  const normalizedDistance = distance / halfLife;
+  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
+
+  // Scale between min and max
+  return minMultiplier + (maxMultiplier - minMultiplier) * decay;
+}
+
+/**
+ * Create an ELO distance filter.
+ *
+ * Penalizes cards that are far from the user's current ELO level
+ * using a smooth Gaussian decay curve. No discontinuities.
+ *
+ * @param config - Optional configuration for the decay curve
+ * @returns A CardFilter that applies ELO distance penalties
+ */
+export function createEloDistanceFilter(config?: EloDistanceConfig): CardFilter {
+  const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
+  const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
+  const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
+
+  return {
+    name: 'ELO Distance Filter',
+
+    async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+      const { course, userElo } = context;
+
+      // Batch fetch ELO data for all cards
+      const cardIds = cards.map((c) => c.cardId);
+      const cardElos = await course.getCardEloData(cardIds);
+
+      return cards.map((card, i) => {
+        const cardElo = cardElos[i]?.global?.score ?? 1000;
+        const distance = Math.abs(cardElo - userElo);
+        const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
+        const newScore = card.score * multiplier;
+
+        const action = multiplier < maxMultiplier - 0.01 ? 'penalized' : 'passed';
+
+        return {
+          ...card,
+          score: newScore,
+          provenance: [
+            ...card.provenance,
+            {
+              strategy: 'eloDistance',
+              strategyName: 'ELO Distance Filter',
+              strategyId: 'ELO_DISTANCE_FILTER',
+              action,
+              score: newScore,
+              reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) → ${multiplier.toFixed(2)}x`,
+            },
+          ],
+        };
+      });
+    },
+  };
+}
+
+// Export defaults for testing
+export { DEFAULT_HALF_LIFE, DEFAULT_MIN_MULTIPLIER, DEFAULT_MAX_MULTIPLIER };

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

@@ -0,0 +1,6 @@
+// Filter types and interfaces
+export type { CardFilter, FilterContext, CardFilterFactory } from './types';
+
+// Filter implementations
+export { createEloDistanceFilter } from './eloDistance';
+export type { EloDistanceConfig } from './eloDistance';

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

@@ -0,0 +1,115 @@
+import type { WeightedCard } from '../index';
+import type { CourseDBInterface } from '../../interfaces/courseDB';
+import type { UserDBInterface } from '../../interfaces/userDB';
+
+// ============================================================================
+// CARD FILTER INTERFACE
+// ============================================================================
+//
+// Filters are pure transforms on a list of WeightedCards.
+// They replace the delegate-wrapping pattern with a simpler model:
+//
+//   cards = Generator.getWeightedCards()
+//   cards = Filter1.transform(cards, context)
+//   cards = Filter2.transform(cards, context)
+//
+// Benefits:
+// - No nested instantiation
+// - Filters don't need to know about delegates
+// - Easy to add/remove/reorder filters
+// - Natural place to hydrate shared data before filter pass
+//
+// All filters should be score multipliers (including score: 0 for exclusion).
+// This means filter order doesn't affect final scores.
+//
+// ============================================================================
+
+/**
+ * Shared context available to all filters in a pipeline.
+ *
+ * Built once per getWeightedCards() call and passed to each filter.
+ * This avoids repeated lookups for common data like user ELO.
+ */
+export interface FilterContext {
+  /** User database interface */
+  user: UserDBInterface;
+
+  /** Course database interface */
+  course: CourseDBInterface;
+
+  /** User's global ELO score for this course */
+  userElo: number;
+
+  // Future extensions:
+  // - hydrated tags for all cards (batch lookup)
+  // - user's tag-level ELO data
+  // - course config
+}
+
+/**
+ * A filter that transforms a list of weighted cards.
+ *
+ * Filters are pure transforms - they receive cards and context,
+ * and return a modified list of cards. No delegate wrapping,
+ * no side effects beyond provenance tracking.
+ *
+ * ## Implementation Guidelines
+ *
+ * 1. **Append provenance**: Every filter should add a StrategyContribution
+ *    entry documenting its decision for each card.
+ *
+ * 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
+ *    This ensures filter order doesn't matter.
+ *
+ * 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
+ *    Don't filter it out - let provenance show why it was excluded.
+ *
+ * 4. **Don't sort**: The Pipeline handles final sorting.
+ *    Filters just transform scores.
+ *
+ * ## Example Implementation
+ *
+ * ```typescript
+ * const myFilter: CardFilter = {
+ *   name: 'My Filter',
+ *   async transform(cards, context) {
+ *     return cards.map(card => {
+ *       const multiplier = computeMultiplier(card, context);
+ *       const newScore = card.score * multiplier;
+ *       return {
+ *         ...card,
+ *         score: newScore,
+ *         provenance: [...card.provenance, {
+ *           strategy: 'myFilter',
+ *           strategyName: 'My Filter',
+ *           strategyId: 'MY_FILTER',
+ *           action: multiplier < 1 ? 'penalized' : 'passed',
+ *           score: newScore,
+ *           reason: 'Explanation of decision'
+ *         }]
+ *       };
+ *     });
+ *   }
+ * };
+ * ```
+ */
+export interface CardFilter {
+  /** Human-readable name for this filter */
+  name: string;
+
+  /**
+   * Transform a list of weighted cards.
+   *
+   * @param cards - Cards to transform (already scored by generator)
+   * @param context - Shared context (user, course, userElo, etc.)
+   * @returns Transformed cards with updated scores and provenance
+   */
+  transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
+}
+
+/**
+ * Factory function type for creating filters from configuration.
+ *
+ * Used by PipelineAssembler to instantiate filters from strategy documents.
+ */
+export type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;

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

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