@vue-skuilder/db 0.1.23 → 0.1.25

package/src/core/navigators/PipelineDebugger.ts

@@ -0,0 +1,426 @@
+import type { WeightedCard, StrategyContribution } from './index';
+import { logger } from '../../util/logger';
+
+// ============================================================================
+// PIPELINE DEBUGGER
+// ============================================================================
+//
+// Console-accessible debug API for inspecting pipeline decisions.
+//
+// Exposed as `window.skuilder.pipeline` for interactive exploration.
+//
+// Usage:
+//   window.skuilder.pipeline.showLastRun()
+//   window.skuilder.pipeline.showCard('cardId123')
+//   window.skuilder.pipeline.explainReviews()
+//   window.skuilder.pipeline.export()
+//
+// ============================================================================
+
+/**
+ * Summary of a single generator's contribution.
+ */
+export interface GeneratorSummary {
+  name: string;
+  cardCount: number;
+  newCount: number;
+  reviewCount: number;
+  topScore: number;
+}
+
+/**
+ * Summary of a filter's impact on scores.
+ */
+export interface FilterImpact {
+  name: string;
+  boosted: number;
+  penalized: number;
+  passed: number;
+  removed: number;
+}
+
+/**
+ * Complete record of a single pipeline execution.
+ */
+export interface PipelineRunReport {
+  runId: string;
+  timestamp: Date;
+  courseId: string;
+  courseName?: string;
+
+  // Generator phase
+  generatorName: string;
+  generators?: GeneratorSummary[];
+  generatedCount: number;
+
+  // Filter phase
+  filters: FilterImpact[];
+
+  // Results
+  finalCount: number;
+  reviewsSelected: number;
+  newSelected: number;
+
+  // Full card data for inspection
+  cards: Array<{
+    cardId: string;
+    courseId: string;
+    origin: 'new' | 'review' | 'unknown';
+    finalScore: number;
+    provenance: StrategyContribution[];
+    selected: boolean;
+  }>;
+}
+
+/**
+ * Ring buffer for storing recent pipeline runs.
+ */
+const MAX_RUNS = 10;
+const runHistory: PipelineRunReport[] = [];
+
+/**
+ * Determine card origin from provenance trail.
+ */
+function getOrigin(card: WeightedCard): 'new' | 'review' | 'unknown' {
+  const firstEntry = card.provenance[0];
+  if (!firstEntry) return 'unknown';
+  const reason = firstEntry.reason?.toLowerCase() || '';
+  if (reason.includes('new card')) return 'new';
+  if (reason.includes('review')) return 'review';
+  return 'unknown';
+}
+
+/**
+ * Capture a pipeline run for later inspection.
+ */
+export function captureRun(report: Omit<PipelineRunReport, 'runId' | 'timestamp'>): void {
+  const fullReport: PipelineRunReport = {
+    ...report,
+    runId: `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    timestamp: new Date(),
+  };
+
+  runHistory.unshift(fullReport);
+  if (runHistory.length > MAX_RUNS) {
+    runHistory.pop();
+  }
+}
+
+/**
+ * Build a capture-ready report from pipeline execution data.
+ */
+export function buildRunReport(
+  courseId: string,
+  courseName: string | undefined,
+  generatorName: string,
+  generators: GeneratorSummary[] | undefined,
+  generatedCount: number,
+  filters: FilterImpact[],
+  allCards: WeightedCard[],
+  selectedCards: WeightedCard[]
+): Omit<PipelineRunReport, 'runId' | 'timestamp'> {
+  const selectedIds = new Set(selectedCards.map((c) => c.cardId));
+
+  const cards = allCards.map((card) => ({
+    cardId: card.cardId,
+    courseId: card.courseId,
+    origin: getOrigin(card),
+    finalScore: card.score,
+    provenance: card.provenance,
+    selected: selectedIds.has(card.cardId),
+  }));
+
+  const reviewsSelected = selectedCards.filter((c) => getOrigin(c) === 'review').length;
+  const newSelected = selectedCards.filter((c) => getOrigin(c) === 'new').length;
+
+  return {
+    courseId,
+    courseName,
+    generatorName,
+    generators,
+    generatedCount,
+    filters,
+    finalCount: selectedCards.length,
+    reviewsSelected,
+    newSelected,
+    cards,
+  };
+}
+
+// ============================================================================
+// CONSOLE API
+// ============================================================================
+
+/**
+ * Format a provenance trail for console display.
+ */
+function formatProvenance(provenance: StrategyContribution[]): string {
+  return provenance
+    .map((p) => {
+      const actionSymbol =
+        p.action === 'generated'
+          ? '🎲'
+          : p.action === 'boosted'
+            ? '⬆️'
+            : p.action === 'penalized'
+              ? '⬇️'
+              : '➡️';
+      return `  ${actionSymbol} ${p.strategyName}: ${p.score.toFixed(3)} - ${p.reason}`;
+    })
+    .join('\n');
+}
+
+/**
+ * Print summary of a single pipeline run.
+ */
+function printRunSummary(run: PipelineRunReport): void {
+  // eslint-disable-next-line no-console
+  console.group(`🔍 Pipeline Run: ${run.courseId} (${run.courseName || 'unnamed'})`);
+  logger.info(`Run ID: ${run.runId}`);
+  logger.info(`Time: ${run.timestamp.toISOString()}`);
+  logger.info(`Generator: ${run.generatorName} → ${run.generatedCount} candidates`);
+
+  if (run.generators && run.generators.length > 0) {
+    // eslint-disable-next-line no-console
+    console.group('Generator breakdown:');
+    for (const g of run.generators) {
+      logger.info(
+        `  ${g.name}: ${g.cardCount} cards (${g.newCount} new, ${g.reviewCount} reviews, top: ${g.topScore.toFixed(2)})`
+      );
+    }
+    // eslint-disable-next-line no-console
+    console.groupEnd();
+  }
+
+  if (run.filters.length > 0) {
+    // eslint-disable-next-line no-console
+    console.group('Filter impact:');
+    for (const f of run.filters) {
+      logger.info(`  ${f.name}: ↑${f.boosted} ↓${f.penalized} =${f.passed} ✕${f.removed}`);
+    }
+    // eslint-disable-next-line no-console
+    console.groupEnd();
+  }
+
+  logger.info(
+    `Result: ${run.finalCount} cards selected (${run.newSelected} new, ${run.reviewsSelected} reviews)`
+  );
+  // eslint-disable-next-line no-console
+  console.groupEnd();
+}
+
+/**
+ * Console API object exposed on window.skuilder.pipeline
+ */
+export const pipelineDebugAPI = {
+  /**
+   * Get raw run history for programmatic access.
+   */
+  get runs(): PipelineRunReport[] {
+    return [...runHistory];
+  },
+
+  /**
+   * Show summary of a specific pipeline run.
+   */
+  showRun(idOrIndex: string | number = 0): void {
+    if (runHistory.length === 0) {
+      logger.info('[Pipeline Debug] No runs captured yet.');
+      return;
+    }
+
+    let run: PipelineRunReport | undefined;
+
+    if (typeof idOrIndex === 'number') {
+      run = runHistory[idOrIndex];
+      if (!run) {
+        logger.info(
+          `[Pipeline Debug] No run found at index ${idOrIndex}. History length: ${runHistory.length}`
+        );
+        return;
+      }
+    } else {
+      run = runHistory.find((r) => r.runId.endsWith(idOrIndex));
+      if (!run) {
+        logger.info(`[Pipeline Debug] No run found matching ID '${idOrIndex}'.`);
+        return;
+      }
+    }
+
+    printRunSummary(run);
+  },
+
+  /**
+   * Show summary of the last pipeline run.
+   */
+  showLastRun(): void {
+    this.showRun(0);
+  },
+
+  /**
+   * Show detailed provenance for a specific card.
+   */
+  showCard(cardId: string): void {
+    for (const run of runHistory) {
+      const card = run.cards.find((c) => c.cardId === cardId);
+      if (card) {
+        // eslint-disable-next-line no-console
+        console.group(`🎴 Card: ${cardId}`);
+        logger.info(`Course: ${card.courseId}`);
+        logger.info(`Origin: ${card.origin}`);
+        logger.info(`Final score: ${card.finalScore.toFixed(3)}`);
+        logger.info(`Selected: ${card.selected ? 'Yes ✅' : 'No ❌'}`);
+        logger.info('Provenance:');
+        logger.info(formatProvenance(card.provenance));
+        // eslint-disable-next-line no-console
+        console.groupEnd();
+        return;
+      }
+    }
+    logger.info(`[Pipeline Debug] Card '${cardId}' not found in recent runs.`);
+  },
+
+  /**
+   * Explain why reviews may or may not have been selected.
+   */
+  explainReviews(): void {
+    if (runHistory.length === 0) {
+      logger.info('[Pipeline Debug] No runs captured yet.');
+      return;
+    }
+
+    // eslint-disable-next-line no-console
+    console.group('📋 Review Selection Analysis');
+
+    for (const run of runHistory) {
+      // eslint-disable-next-line no-console
+      console.group(`Run: ${run.courseId} @ ${run.timestamp.toLocaleTimeString()}`);
+
+      const allReviews = run.cards.filter((c) => c.origin === 'review');
+      const selectedReviews = allReviews.filter((c) => c.selected);
+
+      if (allReviews.length === 0) {
+        logger.info('❌ No reviews were generated. Check SRS logs for why.');
+      } else if (selectedReviews.length === 0) {
+        logger.info(`⚠️ ${allReviews.length} reviews generated but none selected.`);
+        logger.info('Possible reasons:');
+
+        // Check if new cards scored higher
+        const topNewScore = Math.max(
+          ...run.cards.filter((c) => c.origin === 'new' && c.selected).map((c) => c.finalScore),
+          0
+        );
+        const topReviewScore = Math.max(...allReviews.map((c) => c.finalScore), 0);
+
+        if (topReviewScore < topNewScore) {
+          logger.info(
+            `  - New cards scored higher (top new: ${topNewScore.toFixed(2)}, top review: ${topReviewScore.toFixed(2)})`
+          );
+        }
+
+        // Show top review that didn't make it
+        const topReview = allReviews.sort((a, b) => b.finalScore - a.finalScore)[0];
+        if (topReview) {
+          logger.info(`  - Top review score: ${topReview.finalScore.toFixed(3)}`);
+          logger.info('  - Its provenance:');
+          logger.info(formatProvenance(topReview.provenance));
+        }
+      } else {
+        logger.info(`✅ ${selectedReviews.length}/${allReviews.length} reviews selected.`);
+        logger.info('Top selected review:');
+        const topSelected = selectedReviews.sort((a, b) => b.finalScore - a.finalScore)[0];
+        logger.info(formatProvenance(topSelected.provenance));
+      }
+
+      // eslint-disable-next-line no-console
+      console.groupEnd();
+    }
+
+    // eslint-disable-next-line no-console
+    console.groupEnd();
+  },
+
+  /**
+   * Show all runs in compact format.
+   */
+  listRuns(): void {
+    if (runHistory.length === 0) {
+      logger.info('[Pipeline Debug] No runs captured yet.');
+      return;
+    }
+
+    // eslint-disable-next-line no-console
+    console.table(
+      runHistory.map((r) => ({
+        id: r.runId.slice(-8),
+        time: r.timestamp.toLocaleTimeString(),
+        course: r.courseName || r.courseId.slice(0, 8),
+        generated: r.generatedCount,
+        selected: r.finalCount,
+        new: r.newSelected,
+        reviews: r.reviewsSelected,
+      }))
+    );
+  },
+
+  /**
+   * Export run history as JSON for bug reports.
+   */
+  export(): string {
+    const json = JSON.stringify(runHistory, null, 2);
+    logger.info('[Pipeline Debug] Run history exported. Copy the returned string or use:');
+    logger.info('  copy(window.skuilder.pipeline.export())');
+    return json;
+  },
+
+  /**
+   * Clear run history.
+   */
+  clear(): void {
+    runHistory.length = 0;
+    logger.info('[Pipeline Debug] Run history cleared.');
+  },
+
+  /**
+   * Show help.
+   */
+  help(): void {
+    logger.info(`
+🔧 Pipeline Debug API
+
+Commands:
+  .showLastRun()         Show summary of most recent pipeline run
+  .showRun(id|index)     Show summary of a specific run (by index or ID suffix)
+  .showCard(cardId)      Show provenance trail for a specific card
+  .explainReviews()      Analyze why reviews were/weren't selected
+  .listRuns()            List all captured runs in table format
+  .export()              Export run history as JSON for bug reports
+  .clear()               Clear run history
+  .runs                  Access raw run history array
+  .help()                Show this help message
+
+Example:
+  window.skuilder.pipeline.showLastRun()
+  window.skuilder.pipeline.showRun(1)
+  window.skuilder.pipeline.showCard('abc123')
+`);
+  },
+};
+
+// ============================================================================
+// WINDOW MOUNT
+// ============================================================================
+
+/**
+ * Mount the debug API on window.skuilder.pipeline
+ */
+export function mountPipelineDebugger(): void {
+  if (typeof window === 'undefined') return;
+
+  const win = window as any;
+  win.skuilder = win.skuilder || {};
+  win.skuilder.pipeline = pipelineDebugAPI;
+}
+
+// Auto-mount when module is loaded
+mountPipelineDebugger();

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

@@ -0,0 +1,141 @@
+import { CardFilter, FilterContext } from './types';
+import { WeightedCard } from '../index';
+import { LearnableWeight, DEFAULT_LEARNABLE_WEIGHT } from '../../types/contentNavigationStrategy';
+
+/**
+ * Wraps a CardFilter to apply evolutionary weighting to its effects.
+ *
+ * If a filter applies a multiplier M (score * M), and the strategy has
+ * an effective weight W, the final multiplier becomes M^W.
+ *
+ * - W=1.0: Original behavior
+ * - W>1.0: Amplifies the filter's opinion (stronger boost/penalty)
+ * - W<1.0: Dampens the filter's opinion (weaker boost/penalty)
+ * - W=0.0: Nullifies the filter (identity)
+ *
+ * This wrapper handles the math of scaling the filter's impact and updating
+ * the provenance trail with the effective weight used.
+ */
+export class WeightedFilter implements CardFilter {
+  public name: string;
+  private inner: CardFilter;
+  private learnable: LearnableWeight;
+  private staticWeight: boolean;
+  private strategyId?: string;
+
+  constructor(
+    inner: CardFilter,
+    learnable: LearnableWeight = DEFAULT_LEARNABLE_WEIGHT,
+    staticWeight: boolean = false,
+    strategyId?: string
+  ) {
+    this.inner = inner;
+    this.name = inner.name;
+    this.learnable = learnable;
+    this.staticWeight = staticWeight;
+    this.strategyId = strategyId;
+  }
+
+  /**
+   * Apply the inner filter, then scale its effect by the configured weight.
+   */
+  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+    // ========================================================================
+    // 1. DETERMINE EFFECTIVE WEIGHT
+    // ========================================================================
+    
+    // Determine effective weight using orchestration context if available
+    let effectiveWeight = this.learnable.weight;
+    let deviation: number | undefined;
+
+    if (!this.staticWeight && context.orchestration) {
+      // ContentNavigator instances have a strategyId property (protected/private)
+      // We assume inner filter is a ContentNavigator or has a strategyId property.
+      // Fallback to name if not present.
+      const strategyId = this.strategyId || (this.inner as any).strategyId || this.name;
+      effectiveWeight = context.orchestration.getEffectiveWeight(strategyId, this.learnable);
+      deviation = context.orchestration.getDeviation(strategyId);
+    }
+
+    // Optimization: If weight is 1.0, the scaling is an identity operation.
+    // Just run the inner filter directly.
+    if (Math.abs(effectiveWeight - 1.0) < 0.001) {
+      return this.inner.transform(cards, context);
+    }
+
+    // ========================================================================
+    // 2. CAPTURE STATE BEFORE FILTER
+    // ========================================================================
+    
+    // We need original scores to calculate what the filter did (M = new/old)
+    const originalScores = new Map<string, number>();
+    for (const card of cards) {
+      originalScores.set(card.cardId, card.score);
+    }
+
+    // ========================================================================
+    // 3. RUN INNER FILTER
+    // ========================================================================
+    
+    const transformedCards = await this.inner.transform(cards, context);
+
+    // ========================================================================
+    // 4. APPLY WEIGHT SCALING
+    // ========================================================================
+    
+    return transformedCards.map((card) => {
+      const originalScore = originalScores.get(card.cardId);
+
+      // Edge cases where we can't or shouldn't scale:
+      // - Original score missing (shouldn't happen)
+      // - Original score 0 (was already excluded)
+      // - New score 0 (filter excluded it / vetoed) - we treat vetoes as absolute
+      if (originalScore === undefined || originalScore === 0 || card.score === 0) {
+        return card;
+      }
+
+      // Calculate raw effect multiplier: M = new / old
+      const rawEffect = card.score / originalScore;
+
+      // If filter didn't change this card, nothing to scale
+      if (Math.abs(rawEffect - 1.0) < 0.0001) {
+        return card;
+      }
+
+      // Apply weight: scaled = M ^ W
+      // Example: 0.5 penalty ^ 2.0 weight = 0.25 (stronger penalty)
+      // Example: 0.5 penalty ^ 0.5 weight = 0.707 (weaker penalty)
+      const weightedEffect = Math.pow(rawEffect, effectiveWeight);
+      const newScore = originalScore * weightedEffect;
+
+      // Update provenance
+      // The inner filter just added the last entry. We need to update it
+      // to reflect the weighted score and record the effective weight.
+      const lastProvIndex = card.provenance.length - 1;
+      const lastProv = card.provenance[lastProvIndex];
+
+      if (lastProv) {
+        const updatedProvenance = [...card.provenance];
+        updatedProvenance[lastProvIndex] = {
+          ...lastProv,
+          score: newScore,
+          effectiveWeight: effectiveWeight,
+          deviation: deviation,
+          // We can optionally append to the reason, but the structured field is key
+        };
+
+        return {
+          ...card,
+          score: newScore,
+          provenance: updatedProvenance,
+        };
+      }
+
+      // Fallback if no provenance found (rare)
+      return {
+        ...card,
+        score: newScore,
+      };
+    });
+  }
+}

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

@@ -1,6 +1,7 @@
 import type { WeightedCard } from '../index';
 import type { CourseDBInterface } from '../../interfaces/courseDB';
 import type { UserDBInterface } from '../../interfaces/userDB';
+import type { OrchestrationContext } from '../../orchestration';
 
 // ============================================================================
 // CARD FILTER INTERFACE
@@ -40,6 +41,9 @@ export interface FilterContext {
   /** User's global ELO score for this course */
   userElo: number;
 
+  /** Orchestration context for evolutionary weighting */
+  orchestration?: OrchestrationContext;
+
   // Future extensions:
   // - hydrated tags for all cards (batch lookup)
   // - user's tag-level ELO data