@vue-skuilder/db 0.1.17 → 0.1.20

package/src/core/interfaces/courseDB.ts

@@ -92,6 +92,19 @@ export interface CourseDBInterface extends NavigationStrategyManager {
    */
   getAppliedTags(cardId: string): Promise<PouchDB.Query.Response<TagStub>>;
 
+  /**
+   * Get tags for multiple cards in a single batch query.
+   * More efficient than calling getAppliedTags() for each card.
+   *
+   * This method reduces redundant database operations when multiple filters
+   * need tag data for the same cards. The Pipeline uses this to pre-hydrate
+   * tags on WeightedCard objects before filters run.
+   *
+   * @param cardIds - Array of card IDs to fetch tags for
+   * @returns Map from cardId to array of tag names
+   */
+  getAppliedTagsBatch(cardIds: string[]): Promise<Map<string, string[]>>;
+
   /**
    * Add a tag to a card
    */

package/src/core/interfaces/navigationStrategyManager.ts

@@ -33,11 +33,6 @@ export interface NavigationStrategyManager {
    */
   updateNavigationStrategy(id: string, data: ContentNavigationStrategyData): Promise<void>;
 
-  /**
-   * @returns A content navigation strategy suitable to the current context.
-   */
-  surfaceNavigationStrategy(): Promise<ContentNavigationStrategyData>;
-
   // [ ] addons here like:
   //     - determining Navigation Strategy from context of current user
   //     - determining weighted averages of navigation strategies

package/src/core/interfaces/userDB.ts

@@ -56,6 +56,18 @@ export interface UserDBReader {
 
   getActivityRecords(): Promise<ActivityRecord[]>;
 
+  /**
+   * Get strategy-specific state for a course.
+   *
+   * Strategies use this to persist preferences, learned patterns, or temporal
+   * tracking data across sessions. Each strategy owns its own namespace.
+   *
+   * @param courseId - The course this state applies to
+   * @param strategyKey - Unique key identifying the strategy (typically class name)
+   * @returns The strategy's data payload, or null if no state exists
+   */
+  getStrategyState<T>(courseId: string, strategyKey: string): Promise<T | null>;
+
   /**
    * Get user's classroom registrations
    */
@@ -132,6 +144,26 @@ export interface UserDBWriter extends DocumentUpdater {
    * Reset all user data (progress, registrations, etc.) while preserving authentication
    */
   resetUserData(): Promise<{ status: Status; error?: string }>;
+
+  /**
+   * Store strategy-specific state for a course.
+   *
+   * Strategies use this to persist preferences, learned patterns, or temporal
+   * tracking data across sessions. Each strategy owns its own namespace.
+   *
+   * @param courseId - The course this state applies to
+   * @param strategyKey - Unique key identifying the strategy (typically class name)
+   * @param data - The strategy's data payload to store
+   */
+  putStrategyState<T>(courseId: string, strategyKey: string, data: T): Promise<void>;
+
+  /**
+   * Delete strategy-specific state for a course.
+   *
+   * @param courseId - The course this state applies to
+   * @param strategyKey - Unique key identifying the strategy (typically class name)
+   */
+  deleteStrategyState(courseId: string, strategyKey: string): Promise<void>;
 }
 
 /**

package/src/core/navigators/CompositeGenerator.ts

@@ -0,0 +1,268 @@
+import { ContentNavigator } from './index';
+import type { WeightedCard } from './index';
+import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
+import type { CourseDBInterface } from '../interfaces/courseDB';
+import type { UserDBInterface } from '../interfaces/userDB';
+import type { StudySessionNewItem, StudySessionReviewItem } from '../interfaces/contentSource';
+import type { ScheduledCard } from '../types/user';
+import type { CardGenerator, GeneratorContext } from './generators/types';
+import { logger } from '../../util/logger';
+
+// ============================================================================
+// COMPOSITE GENERATOR
+// ============================================================================
+//
+// Composes multiple generator strategies into a single generator.
+//
+// Use case: When a course has multiple generators (e.g., ELO + SRS), this
+// class merges their outputs into a unified candidate list.
+//
+// Aggregation strategy:
+// - Cards appearing in multiple generators get a frequency boost
+// - Score = average(scores) * (1 + 0.1 * (appearances - 1))
+// - This rewards cards that multiple generators agree on
+//
+// ============================================================================
+
+/**
+ * Aggregation modes for combining scores from multiple generators.
+ */
+export enum AggregationMode {
+  /** Use the maximum score from any generator */
+  MAX = 'max',
+  /** Average all scores */
+  AVERAGE = 'average',
+  /** Average with frequency boost: avg * (1 + 0.1 * (n-1)) */
+  FREQUENCY_BOOST = 'frequencyBoost',
+}
+
+const DEFAULT_AGGREGATION_MODE = AggregationMode.FREQUENCY_BOOST;
+const FREQUENCY_BOOST_FACTOR = 0.1;
+
+/**
+ * Composes multiple generators into a single generator.
+ *
+ * Implements CardGenerator for use in Pipeline architecture.
+ * Also extends ContentNavigator for backward compatibility.
+ *
+ * Fetches candidates from all generators, deduplicates by cardId,
+ * and aggregates scores based on the configured mode.
+ */
+export default class CompositeGenerator extends ContentNavigator implements CardGenerator {
+  /** Human-readable name for CardGenerator interface */
+  name: string = 'Composite Generator';
+
+  private generators: CardGenerator[];
+  private aggregationMode: AggregationMode;
+
+  constructor(
+    generators: CardGenerator[],
+    aggregationMode: AggregationMode = DEFAULT_AGGREGATION_MODE
+  ) {
+    super();
+    this.generators = generators;
+    this.aggregationMode = aggregationMode;
+
+    if (generators.length === 0) {
+      throw new Error('CompositeGenerator requires at least one generator');
+    }
+
+    logger.debug(
+      `[CompositeGenerator] Created with ${generators.length} generators, mode: ${aggregationMode}`
+    );
+  }
+
+  /**
+   * Creates a CompositeGenerator from strategy data.
+   *
+   * This is a convenience factory for use by PipelineAssembler.
+   */
+  static async fromStrategies(
+    user: UserDBInterface,
+    course: CourseDBInterface,
+    strategies: ContentNavigationStrategyData[],
+    aggregationMode: AggregationMode = DEFAULT_AGGREGATION_MODE
+  ): Promise<CompositeGenerator> {
+    const generators = await Promise.all(
+      strategies.map((s) => ContentNavigator.create(user, course, s))
+    );
+    // Cast is safe because we know these are generators
+    return new CompositeGenerator(generators as unknown as CardGenerator[], aggregationMode);
+  }
+
+  /**
+   * Get weighted cards from all generators, merge and deduplicate.
+   *
+   * Cards appearing in multiple generators receive a score boost.
+   * Provenance tracks which generators produced each card and how scores were aggregated.
+   *
+   * 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 passed to child generators
+   */
+  async getWeightedCards(limit: number, context?: GeneratorContext): Promise<WeightedCard[]> {
+    // Fetch from all generators in parallel
+    const results = await Promise.all(
+      this.generators.map((g) => g.getWeightedCards(limit, context))
+    );
+
+    // Group by cardId
+    const byCardId = new Map<string, WeightedCard[]>();
+    for (const cards of results) {
+      for (const card of cards) {
+        const existing = byCardId.get(card.cardId) || [];
+        existing.push(card);
+        byCardId.set(card.cardId, existing);
+      }
+    }
+
+    // Aggregate scores
+    const merged: WeightedCard[] = [];
+    for (const [, cards] of byCardId) {
+      const aggregatedScore = this.aggregateScores(cards);
+      const finalScore = Math.min(1.0, aggregatedScore); // Clamp to [0, 1]
+
+      // Merge provenance from all generators that produced this card
+      const mergedProvenance = cards.flatMap((c) => c.provenance);
+
+      // Determine action based on whether score changed
+      const initialScore = cards[0].score;
+      const action =
+        finalScore > initialScore ? 'boosted' : finalScore < initialScore ? 'penalized' : 'passed';
+
+      // Build reason explaining the aggregation
+      const reason = this.buildAggregationReason(cards, finalScore);
+
+      // Append composite provenance entry
+      merged.push({
+        ...cards[0],
+        score: finalScore,
+        provenance: [
+          ...mergedProvenance,
+          {
+            strategy: 'composite',
+            strategyName: 'Composite Generator',
+            strategyId: 'COMPOSITE_GENERATOR',
+            action,
+            score: finalScore,
+            reason,
+          },
+        ],
+      });
+    }
+
+    // Sort by score descending and limit
+    return merged.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+
+  /**
+   * Build human-readable reason for score aggregation.
+   */
+  private buildAggregationReason(cards: WeightedCard[], finalScore: number): string {
+    const count = cards.length;
+    const scores = cards.map((c) => c.score.toFixed(2)).join(', ');
+
+    if (count === 1) {
+      return `Single generator, score ${finalScore.toFixed(2)}`;
+    }
+
+    const strategies = cards.map((c) => c.provenance[0]?.strategy || 'unknown').join(', ');
+
+    switch (this.aggregationMode) {
+      case AggregationMode.MAX:
+        return `Max of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
+
+      case AggregationMode.AVERAGE:
+        return `Average of ${count} generators (${strategies}): scores [${scores}] → ${finalScore.toFixed(2)}`;
+
+      case AggregationMode.FREQUENCY_BOOST: {
+        const avg = cards.reduce((sum, c) => sum + c.score, 0) / count;
+        const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);
+        return `Frequency boost from ${count} generators (${strategies}): avg ${avg.toFixed(2)} × ${boost.toFixed(2)} → ${finalScore.toFixed(2)}`;
+      }
+
+      default:
+        return `Aggregated from ${count} generators: ${finalScore.toFixed(2)}`;
+    }
+  }
+
+  /**
+   * Aggregate scores from multiple generators for the same card.
+   */
+  private aggregateScores(cards: WeightedCard[]): number {
+    const scores = cards.map((c) => c.score);
+
+    switch (this.aggregationMode) {
+      case AggregationMode.MAX:
+        return Math.max(...scores);
+
+      case AggregationMode.AVERAGE:
+        return scores.reduce((sum, s) => sum + s, 0) / scores.length;
+
+      case AggregationMode.FREQUENCY_BOOST: {
+        const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length;
+        const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (cards.length - 1);
+        return avg * frequencyBoost;
+      }
+
+      default:
+        return scores[0];
+    }
+  }
+
+  /**
+   * Get new cards from all generators, merged and deduplicated.
+   */
+  async getNewCards(n?: number): Promise<StudySessionNewItem[]> {
+    // For legacy method, need to filter to generators that have getNewCards
+    const legacyGenerators = this.generators.filter(
+      (g): g is CardGenerator & ContentNavigator => g instanceof ContentNavigator
+    );
+
+    const results = await Promise.all(legacyGenerators.map((g) => g.getNewCards(n)));
+
+    // Deduplicate by cardID
+    const seen = new Set<string>();
+    const merged: StudySessionNewItem[] = [];
+
+    for (const cards of results) {
+      for (const card of cards) {
+        if (!seen.has(card.cardID)) {
+          seen.add(card.cardID);
+          merged.push(card);
+        }
+      }
+    }
+
+    return n ? merged.slice(0, n) : merged;
+  }
+
+  /**
+   * Get pending reviews from all generators, merged and deduplicated.
+   */
+  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
+    // For legacy method, need to filter to generators that have getPendingReviews
+    const legacyGenerators = this.generators.filter(
+      (g): g is CardGenerator & ContentNavigator => g instanceof ContentNavigator
+    );
+
+    const results = await Promise.all(legacyGenerators.map((g) => g.getPendingReviews()));
+
+    // Deduplicate by cardID
+    const seen = new Set<string>();
+    const merged: (StudySessionReviewItem & ScheduledCard)[] = [];
+
+    for (const reviews of results) {
+      for (const review of reviews) {
+        if (!seen.has(review.cardID)) {
+          seen.add(review.cardID);
+          merged.push(review);
+        }
+      }
+    }
+
+    return merged;
+  }
+}

package/src/core/navigators/Pipeline.ts

@@ -0,0 +1,318 @@
+import { toCourseElo } from '@vue-skuilder/common';
+import type { CourseDBInterface } from '../interfaces/courseDB';
+import type { UserDBInterface } from '../interfaces/userDB';
+import type { ScheduledCard } from '../types/user';
+import { ContentNavigator } from './index';
+import type { WeightedCard } from './index';
+import type { CardFilter, FilterContext } from './filters/types';
+import type { CardGenerator, GeneratorContext } from './generators/types';
+import type { StudySessionNewItem, StudySessionReviewItem } from '../interfaces/contentSource';
+import { logger } from '../../util/logger';
+
+// ============================================================================
+// PIPELINE LOGGING HELPERS
+// ============================================================================
+//
+// Focused logging functions that can be toggled by commenting single lines.
+// Use these to inspect pipeline behavior in development/production.
+//
+
+/**
+ * Log pipeline configuration on construction.
+ * Shows generator and filter chain structure.
+ */
+function logPipelineConfig(generator: CardGenerator, filters: CardFilter[]): void {
+  const filterList = filters.length > 0
+    ? '\n    - ' + filters.map(f => f.name).join('\n    - ')
+    : ' none';
+
+  logger.info(
+    `[Pipeline] Configuration:\n` +
+    `  Generator: ${generator.name}\n` +
+    `  Filters:${filterList}`
+  );
+}
+
+/**
+ * Log tag hydration results.
+ * Shows effectiveness of batch query (how many cards/tags were hydrated).
+ */
+function logTagHydration(cards: WeightedCard[], tagsByCard: Map<string, string[]>): void {
+  const totalTags = Array.from(tagsByCard.values()).reduce((sum, tags) => sum + tags.length, 0);
+  const cardsWithTags = Array.from(tagsByCard.values()).filter(tags => tags.length > 0).length;
+
+  logger.debug(
+    `[Pipeline] Tag hydration: ${cards.length} cards, ` +
+    `${cardsWithTags} have tags (${totalTags} total tags) - single batch query`
+  );
+}
+
+/**
+ * Log pipeline execution summary.
+ * Shows complete flow from generator through filters to final results.
+ */
+function logExecutionSummary(
+  generatorName: string,
+  generatedCount: number,
+  filterCount: number,
+  finalCount: number,
+  topScores: number[]
+): void {
+  const scoreDisplay = topScores.length > 0
+    ? topScores.map(s => s.toFixed(2)).join(', ')
+    : 'none';
+
+  logger.info(
+    `[Pipeline] Execution: ${generatorName} produced ${generatedCount} → ` +
+    `${filterCount} filters → ${finalCount} results (top scores: ${scoreDisplay})`
+  );
+}
+
+/**
+ * Log provenance trails for cards.
+ * Shows the complete scoring history for each card through the pipeline.
+ * Useful for debugging why cards scored the way they did.
+ */
+function logCardProvenance(cards: WeightedCard[], maxCards: number = 3): void {
+  const cardsToLog = cards.slice(0, maxCards);
+
+  logger.debug(`[Pipeline] Provenance for top ${cardsToLog.length} cards:`);
+
+  for (const card of cardsToLog) {
+    logger.debug(`[Pipeline]   ${card.cardId} (final score: ${card.score.toFixed(3)}):`);
+
+    for (const entry of card.provenance) {
+      const scoreChange = entry.score.toFixed(3);
+      const action = entry.action.padEnd(9); // Align columns
+      logger.debug(
+        `[Pipeline]     ${action} ${scoreChange} - ${entry.strategyName}: ${entry.reason}`
+      );
+    }
+  }
+}
+
+// ============================================================================
+// PIPELINE
+// ============================================================================
+//
+// Executes a navigation pipeline: generator → filters → sorted results.
+//
+// Architecture:
+//   cards = generator.getWeightedCards(limit, context)
+//   cards = filter1.transform(cards, context)
+//   cards = filter2.transform(cards, context)
+//   cards = filter3.transform(cards, context)
+//   return sorted(cards).slice(0, limit)
+//
+// Benefits:
+// - Clear separation: generators produce, filters transform
+// - No nested instantiation complexity
+// - Filters don't need to know about each other
+// - Shared context built once, passed to all stages
+//
+// ============================================================================
+
+/**
+ * A navigation pipeline that runs a generator and applies filters sequentially.
+ *
+ * Implements StudyContentSource for backward compatibility with SessionController.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const pipeline = new Pipeline(
+ *   compositeGenerator,  // or single generator
+ *   [eloDistanceFilter, interferenceFilter],
+ *   user,
+ *   course
+ * );
+ *
+ * const cards = await pipeline.getWeightedCards(20);
+ * ```
+ */
+export class Pipeline extends ContentNavigator {
+  private generator: CardGenerator;
+  private filters: CardFilter[];
+
+  /**
+   * Create a new pipeline.
+   *
+   * @param generator - The generator (or CompositeGenerator) that produces candidates
+   * @param filters - Filters to apply sequentially (order doesn't matter for multipliers)
+   * @param user - User database interface
+   * @param course - Course database interface
+   */
+  constructor(
+    generator: CardGenerator,
+    filters: CardFilter[],
+    user: UserDBInterface,
+    course: CourseDBInterface
+  ) {
+    super();
+    this.generator = generator;
+    this.filters = filters;
+    this.user = user;
+    this.course = course;
+
+    // Toggle pipeline configuration logging:
+    logPipelineConfig(generator, filters);
+  }
+
+  /**
+   * Get weighted cards by running generator and applying filters.
+   *
+   * 1. Build shared context (user ELO, etc.)
+   * 2. Get candidates from generator (passing context)
+   * 3. Batch hydrate tags for all candidates
+   * 4. Apply each filter sequentially
+   * 5. Remove zero-score cards
+   * 6. Sort by score descending
+   * 7. Return top N
+   *
+   * @param limit - Maximum number of cards to return
+   * @returns Cards sorted by score descending
+   */
+  async getWeightedCards(limit: number): Promise<WeightedCard[]> {
+    // Build shared context once
+    const context = await this.buildContext();
+
+    // Over-fetch from generator to account for filtering
+    const overFetchMultiplier = 2 + this.filters.length * 0.5;
+    const fetchLimit = Math.ceil(limit * overFetchMultiplier);
+
+    logger.debug(
+      `[Pipeline] Fetching ${fetchLimit} candidates from generator '${this.generator.name}'`
+    );
+
+    // Get candidates from generator, passing context
+    let cards = await this.generator.getWeightedCards(fetchLimit, context);
+    const generatedCount = cards.length;
+
+    logger.debug(`[Pipeline] Generator returned ${generatedCount} candidates`);
+
+    // Batch hydrate tags before filters run
+    cards = await this.hydrateTags(cards);
+
+    // Apply filters sequentially
+    for (const filter of this.filters) {
+      const beforeCount = cards.length;
+      cards = await filter.transform(cards, context);
+      logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeCount} → ${cards.length} cards`);
+    }
+
+    // Remove zero-score cards (hard filtered)
+    cards = cards.filter((c) => c.score > 0);
+
+    // Sort by score descending
+    cards.sort((a, b) => b.score - a.score);
+
+    // Return top N
+    const result = cards.slice(0, limit);
+
+    // Toggle execution summary logging:
+    const topScores = result.slice(0, 3).map(c => c.score);
+    logExecutionSummary(this.generator.name, generatedCount, this.filters.length, result.length, topScores);
+
+    // Toggle provenance logging (shows scoring history for top cards):
+    logCardProvenance(result, 3);
+
+    return result;
+  }
+
+  /**
+   * Batch hydrate tags for all cards.
+   *
+   * Fetches tags for all cards in a single database query and attaches them
+   * to the WeightedCard objects. Filters can then use card.tags instead of
+   * making individual getAppliedTags() calls.
+   *
+   * @param cards - Cards to hydrate
+   * @returns Cards with tags populated
+   */
+  private async hydrateTags(cards: WeightedCard[]): Promise<WeightedCard[]> {
+    if (cards.length === 0) {
+      return cards;
+    }
+
+    const cardIds = cards.map((c) => c.cardId);
+    const tagsByCard = await this.course!.getAppliedTagsBatch(cardIds);
+
+    // Toggle tag hydration logging:
+    logTagHydration(cards, tagsByCard);
+
+    return cards.map((card) => ({
+      ...card,
+      tags: tagsByCard.get(card.cardId) ?? [],
+    }));
+  }
+
+  /**
+   * Build shared context for generator and filters.
+   *
+   * Called once per getWeightedCards() invocation.
+   * Contains data that the generator and multiple filters might need.
+   *
+   * The context satisfies both GeneratorContext and FilterContext interfaces.
+   */
+  private async buildContext(): Promise<GeneratorContext & FilterContext> {
+    let userElo = 1000; // Default ELO
+
+    try {
+      const courseReg = await this.user!.getCourseRegDoc(this.course!.getCourseID());
+      const courseElo = toCourseElo(courseReg.elo);
+      userElo = courseElo.global.score;
+    } catch (e) {
+      logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
+    }
+
+    return {
+      user: this.user!,
+      course: this.course!,
+      userElo,
+    };
+  }
+
+  // ===========================================================================
+  // Legacy StudyContentSource methods
+  // ===========================================================================
+  //
+  // These delegate to the generator for backward compatibility.
+  // Eventually SessionController will use getWeightedCards() exclusively.
+  //
+
+  /**
+   * Get new cards via legacy API.
+   * Delegates to the generator if it supports the legacy interface.
+   */
+  async getNewCards(n?: number): Promise<StudySessionNewItem[]> {
+    // Check if generator has legacy method (ContentNavigator-based generators do)
+    if ('getNewCards' in this.generator && typeof this.generator.getNewCards === 'function') {
+      return (this.generator as ContentNavigator).getNewCards(n);
+    }
+    // Pure CardGenerator without legacy support - return empty
+    return [];
+  }
+
+  /**
+   * Get pending reviews via legacy API.
+   * Delegates to the generator if it supports the legacy interface.
+   */
+  async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
+    // Check if generator has legacy method (ContentNavigator-based generators do)
+    if (
+      'getPendingReviews' in this.generator &&
+      typeof this.generator.getPendingReviews === 'function'
+    ) {
+      return (this.generator as ContentNavigator).getPendingReviews();
+    }
+    // Pure CardGenerator without legacy support - return empty
+    return [];
+  }
+
+  /**
+   * Get the course ID for this pipeline.
+   */
+  getCourseID(): string {
+    return this.course!.getCourseID();
+  }
+}