@vue-skuilder/db 0.1.22 → 0.1.24

package/src/core/orchestration/learning.ts

@@ -0,0 +1,250 @@
+import { LearnableWeight, DEFAULT_LEARNABLE_WEIGHT } from '../types/contentNavigationStrategy';
+import { StrategyLearningState, GradientResult } from '../types/learningState';
+import { DocType } from '../types/types-legacy';
+import { logger } from '../../util/logger';
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Minimum observations required before adjusting weight */
+const MIN_OBSERVATIONS_FOR_UPDATE = 10;
+
+/** How much to adjust weight per gradient unit */
+const LEARNING_RATE = 0.1;
+
+/** Maximum weight adjustment per update cycle */
+const MAX_WEIGHT_DELTA = 0.3;
+
+/** R-squared threshold below which we consider gradient unreliable */
+const MIN_R_SQUARED_FOR_GRADIENT = 0.05;
+
+/** Gradient magnitude below which we consider it "flat" (near optimal) */
+const FLAT_GRADIENT_THRESHOLD = 0.02;
+
+/** Maximum history entries to retain */
+const MAX_HISTORY_LENGTH = 100;
+
+// ============================================================================
+// WEIGHT UPDATE
+// ============================================================================
+
+/**
+ * Compute updated weight based on gradient result.
+ *
+ * The update logic:
+ * - Positive gradient: users with higher weight did better → increase weight
+ * - Negative gradient: users with higher weight did worse → decrease weight
+ * - Flat gradient: weight doesn't affect outcome → increase confidence
+ *
+ * @param current - Current learnable weight
+ * @param gradient - Computed gradient result
+ * @returns Updated learnable weight
+ */
+export function updateStrategyWeight(
+  current: LearnableWeight,
+  gradient: GradientResult
+): LearnableWeight {
+  // Not enough data to make reliable updates
+  if (gradient.sampleSize < MIN_OBSERVATIONS_FOR_UPDATE) {
+    logger.debug(
+      `[Orchestration] Insufficient samples (${gradient.sampleSize} < ${MIN_OBSERVATIONS_FOR_UPDATE}), ` +
+        `keeping current weight`
+    );
+    return {
+      ...current,
+      sampleSize: current.sampleSize + gradient.sampleSize,
+    };
+  }
+
+  // Check if gradient is reliable (R² threshold)
+  const isReliable = gradient.rSquared >= MIN_R_SQUARED_FOR_GRADIENT;
+  const isFlat = Math.abs(gradient.gradient) < FLAT_GRADIENT_THRESHOLD;
+
+  let newWeight = current.weight;
+  let newConfidence = current.confidence;
+
+  if (!isReliable || isFlat) {
+    // Gradient is unreliable or flat - we're likely near optimal
+    // Increase confidence (narrow the exploration spread)
+    const confidenceGain = 0.05 * (1 - current.confidence);
+    newConfidence = Math.min(1.0, current.confidence + confidenceGain);
+
+    logger.debug(
+      `[Orchestration] Flat/unreliable gradient (|g|=${Math.abs(gradient.gradient).toFixed(4)}, ` +
+        `R²=${gradient.rSquared.toFixed(4)}). Increasing confidence: ${current.confidence.toFixed(3)} → ${newConfidence.toFixed(3)}`
+    );
+  } else {
+    // Reliable gradient - adjust weight in gradient direction
+    // Scale by learning rate and clamp to max delta
+    let delta = gradient.gradient * LEARNING_RATE;
+    delta = Math.max(-MAX_WEIGHT_DELTA, Math.min(MAX_WEIGHT_DELTA, delta));
+
+    newWeight = current.weight + delta;
+
+    // Clamp weight to reasonable bounds
+    newWeight = Math.max(0.1, Math.min(3.0, newWeight));
+
+    // Slight confidence increase for having made an observation
+    const confidenceGain = 0.02 * (1 - current.confidence);
+    newConfidence = Math.min(1.0, current.confidence + confidenceGain);
+
+    logger.debug(
+      `[Orchestration] Adjusting weight: ${current.weight.toFixed(3)} → ${newWeight.toFixed(3)} ` +
+        `(gradient=${gradient.gradient.toFixed(4)}, delta=${delta.toFixed(4)})`
+    );
+  }
+
+  return {
+    weight: newWeight,
+    confidence: newConfidence,
+    sampleSize: current.sampleSize + gradient.sampleSize,
+  };
+}
+
+// ============================================================================
+// LEARNING STATE MANAGEMENT
+// ============================================================================
+
+/**
+ * Create or update a StrategyLearningState document.
+ *
+ * @param courseId - Course ID
+ * @param strategyId - Strategy ID
+ * @param currentWeight - Current learned weight
+ * @param gradient - Gradient result from recent computation
+ * @param existing - Existing learning state (if any)
+ * @returns Updated learning state document
+ */
+export function updateLearningState(
+  courseId: string,
+  strategyId: string,
+  currentWeight: LearnableWeight,
+  gradient: GradientResult,
+  existing?: StrategyLearningState
+): StrategyLearningState {
+  const now = new Date().toISOString();
+  const id = `STRATEGY_LEARNING_STATE::${courseId}::${strategyId}`;
+
+  // Build history entry
+  const historyEntry = {
+    timestamp: now,
+    weight: currentWeight.weight,
+    confidence: currentWeight.confidence,
+    gradient: gradient.gradient,
+  };
+
+  // Append to existing history or start fresh
+  let history = existing?.history ?? [];
+  history = [...history, historyEntry];
+
+  // Trim history if too long
+  if (history.length > MAX_HISTORY_LENGTH) {
+    history = history.slice(history.length - MAX_HISTORY_LENGTH);
+  }
+
+  const state: StrategyLearningState = {
+    _id: id,
+    _rev: existing?._rev,
+    docType: DocType.STRATEGY_LEARNING_STATE,
+    courseId,
+    strategyId,
+    currentWeight,
+    regression: {
+      gradient: gradient.gradient,
+      intercept: gradient.intercept,
+      rSquared: gradient.rSquared,
+      sampleSize: gradient.sampleSize,
+      computedAt: now,
+    },
+    history,
+    updatedAt: now,
+  };
+
+  return state;
+}
+
+// ============================================================================
+// PERIOD UPDATE ORCHESTRATOR
+// ============================================================================
+
+/**
+ * Input data for running a period update on a single strategy.
+ */
+export interface PeriodUpdateInput {
+  courseId: string;
+  strategyId: string;
+  currentWeight: LearnableWeight;
+  gradient: GradientResult;
+  existingState?: StrategyLearningState;
+}
+
+/**
+ * Result of a period update for a single strategy.
+ */
+export interface PeriodUpdateResult {
+  strategyId: string;
+  previousWeight: LearnableWeight;
+  newWeight: LearnableWeight;
+  gradient: GradientResult;
+  learningState: StrategyLearningState;
+  updated: boolean;
+}
+
+/**
+ * Run a period update for a single strategy.
+ *
+ * This function:
+ * 1. Takes the computed gradient
+ * 2. Computes the new weight
+ * 3. Generates the updated learning state
+ *
+ * Note: Actual persistence (updating strategy doc, saving learning state)
+ * must be done by the caller with appropriate DB access.
+ *
+ * @param input - Update input data
+ * @returns Update result with new weight and learning state
+ */
+export function runPeriodUpdate(input: PeriodUpdateInput): PeriodUpdateResult {
+  const { courseId, strategyId, currentWeight, gradient, existingState } = input;
+
+  logger.info(
+    `[Orchestration] Running period update for strategy ${strategyId} ` +
+      `(${gradient.sampleSize} observations)`
+  );
+
+  // Compute new weight
+  const newWeight = updateStrategyWeight(currentWeight, gradient);
+  const updated = newWeight.weight !== currentWeight.weight;
+
+  // Generate learning state
+  const learningState = updateLearningState(
+    courseId,
+    strategyId,
+    newWeight,
+    gradient,
+    existingState
+  );
+
+  logger.info(
+    `[Orchestration] Period update complete for ${strategyId}: ` +
+      `weight ${currentWeight.weight.toFixed(3)} → ${newWeight.weight.toFixed(3)}, ` +
+      `confidence ${currentWeight.confidence.toFixed(3)} → ${newWeight.confidence.toFixed(3)}`
+  );
+
+  return {
+    strategyId,
+    previousWeight: currentWeight,
+    newWeight,
+    gradient,
+    learningState,
+    updated,
+  };
+}
+
+/**
+ * Create a default LearnableWeight for strategies that don't have one.
+ */
+export function getDefaultLearnableWeight(): LearnableWeight {
+  return { ...DEFAULT_LEARNABLE_WEIGHT };
+}

package/src/core/orchestration/recording.ts

@@ -0,0 +1,92 @@
+import { OrchestrationContext } from './index';
+import { computeOutcomeSignal, SignalConfig } from './signal';
+import { UserOutcomeRecord } from '../types/userOutcome';
+import { DocType, QuestionRecord } from '../types/types-legacy';
+import { logger } from '../../util/logger';
+
+/**
+ * Records a learning outcome for a specific period of time.
+ *
+ * This function:
+ * 1. Computes a scalar "success" signal from the provided question records
+ * 2. Re-computes the deviations that were active for this user/course
+ * 3. Persists a UserOutcomeRecord to the user's database
+ *
+ * This record is later used by the optimization job to correlate
+ * deviations with outcomes (Evolutionary Orchestration).
+ *
+ * @param context - Orchestration context (user, course, etc.)
+ * @param periodStart - ISO timestamp of period start
+ * @param periodEnd - ISO timestamp of period end (now)
+ * @param records - Question records generated during this period
+ * @param activeStrategyIds - IDs of strategies active in this course
+ * @param eloStart - User's ELO at start of period (optional)
+ * @param eloEnd - User's ELO at end of period (optional)
+ * @param config - Optional configuration for signal computation
+ */
+export async function recordUserOutcome(
+  context: OrchestrationContext,
+  periodStart: string,
+  periodEnd: string,
+  records: QuestionRecord[],
+  activeStrategyIds: string[],
+  eloStart: number = 0,
+  eloEnd: number = 0,
+  config?: SignalConfig
+): Promise<void> {
+  const { user, course, userId } = context;
+  const courseId = course.getCourseID();
+
+  // 1. Compute Signal
+  // If we have no records, we can't determine an outcome.
+  const outcomeValue = computeOutcomeSignal(records, config);
+
+  if (outcomeValue === null) {
+    logger.debug(
+      `[Orchestration] No outcome signal computed for ${userId} (insufficient data). Skipping record.`
+    );
+    return;
+  }
+
+  // 2. Capture Deviations
+  // We re-compute the deterministic deviations for all active strategies.
+  // This tells the learning algorithm "what parameter adjustments were active
+  // when this outcome was achieved".
+  const deviations: Record<string, number> = {};
+  for (const strategyId of activeStrategyIds) {
+    deviations[strategyId] = context.getDeviation(strategyId);
+  }
+
+  // 3. Construct Record
+  // ID format: USER_OUTCOME::{courseId}::{userId}::{periodEnd}
+  // This ensures uniqueness per user/course/time-period.
+  const id = `USER_OUTCOME::${courseId}::${userId}::${periodEnd}`;
+
+  const record: UserOutcomeRecord = {
+    _id: id,
+    docType: DocType.USER_OUTCOME,
+    courseId,
+    userId,
+    periodStart,
+    periodEnd,
+    outcomeValue,
+    deviations,
+    metadata: {
+      sessionsCount: 1, // Assumes recording is triggered per-session currently
+      cardsSeen: records.length,
+      eloStart,
+      eloEnd,
+      signalType: 'accuracy_in_zone',
+    },
+  };
+
+  // 4. Persist
+  try {
+    await user.putUserOutcome(record);
+    logger.debug(
+      `[Orchestration] Recorded outcome ${outcomeValue.toFixed(3)} for ${userId} (doc: ${id})`
+    );
+  } catch (e) {
+    logger.error(`[Orchestration] Failed to record outcome: ${e}`);
+  }
+}

package/src/core/orchestration/signal.ts

@@ -0,0 +1,67 @@
+import { QuestionRecord } from '../types/types-legacy';
+
+export interface SignalConfig {
+  /** Target accuracy for "in the zone" learning (default: 0.85) */
+  targetAccuracy?: number;
+  /** Width of the peak plateau (default: 0.05) */
+  tolerance?: number;
+}
+
+/**
+ * Computes a scalar signal (0-1) representing the quality of the learning outcome.
+ *
+ * Current implementation focuses on "accuracy within Zone of Proximal Development".
+ * Future versions should include ELO gain rate.
+ *
+ * @param records - List of question attempts in the period
+ * @param config - Configuration for the signal function
+ * @returns Score 0.0-1.0, or null if insufficient data
+ */
+export function computeOutcomeSignal(
+  records: QuestionRecord[],
+  config: SignalConfig = {}
+): number | null {
+  if (!records || records.length === 0) {
+    return null;
+  }
+
+  const target = config.targetAccuracy ?? 0.85;
+  const tolerance = config.tolerance ?? 0.05;
+
+  let correct = 0;
+  for (const r of records) {
+    // Cast to any to avoid type error if Evaluation interface is not correctly propagated
+     
+    if ((r as any).isCorrect) correct++;
+  }
+
+  const accuracy = correct / records.length;
+
+  return scoreAccuracyInZone(accuracy, target, tolerance);
+}
+
+/**
+ * Scores an accuracy value based on how close it is to the target "sweet spot".
+ *
+ * The function defines a plateau of width (2 * tolerance) around the target
+ * where score is 1.0. Outside this plateau, it falls off linearly.
+ *
+ * @param accuracy - Observed accuracy (0-1)
+ * @param target - Target accuracy (e.g. 0.85)
+ * @param tolerance - +/- range allowed for max score
+ */
+export function scoreAccuracyInZone(accuracy: number, target: number, tolerance: number): number {
+  const dist = Math.abs(accuracy - target);
+
+  // Inside the sweet spot
+  if (dist <= tolerance) {
+    return 1.0;
+  }
+
+  // Outside, fall off.
+  // We apply a linear penalty for deviation from the tolerance edge.
+  const excess = dist - tolerance;
+  const slope = 2.5; // Falloff rate (0.4 deviation = 0 score)
+
+  return Math.max(0, 1.0 - excess * slope);
+}

package/src/core/types/contentNavigationStrategy.ts

@@ -1,6 +1,31 @@
 import { DocType, SkuilderCourseData } from './types-legacy';
 import type { DocTypePrefixes } from './types-legacy';
 
+/**
+ * Configuration for an evolutionarily-weighted strategy.
+ *
+ * This structure tracks the "learned" weight of a strategy, representing the
+ * system's confidence in its utility.
+ *
+ * - weight: The best-known multiplier (peak of the bell curve)
+ * - confidence: How certain we are (inverse of variance / spread)
+ * - sampleSize: How many data points informed this weight
+ */
+export interface LearnableWeight {
+  /** The current best estimate of optimal weight (multiplier) */
+  weight: number;
+  /** Confidence in this weight (0-1). Higher = narrower exploration spread. */
+  confidence: number;
+  /** Number of outcome observations that contributed to this weight */
+  sampleSize: number;
+}
+
+export const DEFAULT_LEARNABLE_WEIGHT: LearnableWeight = {
+  weight: 1.0,
+  confidence: 0.1, // Low confidence initially = wide exploration
+  sampleSize: 0,
+};
+
 /**
  *
  */
@@ -19,4 +44,17 @@ export interface ContentNavigationStrategyData extends SkuilderCourseData {
    by the implementing class's constructor at runtime.
   */
   serializedData: string;
+
+  /**
+   * Evolutionary weighting configuration.
+   * If present, the strategy's influence is scaled by this weight.
+   * If omitted, weight defaults to 1.0.
+   */
+  learnable?: LearnableWeight;
+
+  /**
+   * If true, the weight is applied exactly as configured, without
+   * per-user deviation. Used for manual tuning or A/B testing.
+   */
+  staticWeight?: boolean;
 }

package/src/core/types/learningState.ts

@@ -0,0 +1,77 @@
+import { DocType } from './types-legacy';
+import { LearnableWeight } from './contentNavigationStrategy';
+
+/**
+ * Snapshot of the learning state for a strategy.
+ *
+ * Stored in the CourseDB for observability and debugging.
+ * Updated periodically by the gradient learning system.
+ */
+export interface StrategyLearningState {
+  /**
+   * Unique ID: "STRATEGY_LEARNING_STATE::{courseId}::{strategyId}"
+   */
+  _id: string;
+
+  /** Allow CouchDB to manage revisions */
+  _rev?: string;
+
+  docType: DocType.STRATEGY_LEARNING_STATE;
+
+  courseId: string;
+  strategyId: string;
+
+  /** Current learned weight (mirrors the strategy doc, for convenience) */
+  currentWeight: LearnableWeight;
+
+  /** Most recent regression statistics */
+  regression: {
+    /** Slope of the linear regression (deviation vs outcome) */
+    gradient: number;
+    /** Y-intercept of the regression line */
+    intercept: number;
+    /** R-squared value (0-1), measure of fit quality */
+    rSquared: number;
+    /** Number of observations used in this regression */
+    sampleSize: number;
+    /** ISO timestamp of when this regression was computed */
+    computedAt: string;
+  };
+
+  /** Historical weight snapshots for visualization */
+  history: Array<{
+    timestamp: string;
+    weight: number;
+    confidence: number;
+    gradient: number;
+  }>;
+
+  /** ISO timestamp of last update */
+  updatedAt: string;
+}
+
+/**
+ * Data point for gradient computation: (deviation, outcome) pair.
+ */
+export interface GradientObservation {
+  /** User's deviation for this strategy [-1, 1] */
+  deviation: number;
+  /** User's outcome value [0, 1] */
+  outcomeValue: number;
+  /** Optional: weight for this observation (default 1.0) */
+  weight?: number;
+}
+
+/**
+ * Result of linear regression on (deviation, outcome) pairs.
+ */
+export interface GradientResult {
+  /** Slope: positive = higher deviation correlates with better outcomes */
+  gradient: number;
+  /** Y-intercept */
+  intercept: number;
+  /** R-squared: 0-1, how well the line fits */
+  rSquared: number;
+  /** Number of observations */
+  sampleSize: number;
+}

package/src/core/types/types-legacy.ts

@@ -20,6 +20,8 @@ export enum DocType {
   TAG = 'TAG',
   NAVIGATION_STRATEGY = 'NAVIGATION_STRATEGY',
   STRATEGY_STATE = 'STRATEGY_STATE',
+  USER_OUTCOME = 'USER_OUTCOME',
+  STRATEGY_LEARNING_STATE = 'STRATEGY_LEARNING_STATE',
 }
 
 export interface QualifiedCardID {
@@ -105,6 +107,8 @@ export const DocTypePrefixes = {
   [DocType.PEDAGOGY]: 'PEDAGOGY',
   [DocType.NAVIGATION_STRATEGY]: 'NAVIGATION_STRATEGY',
   [DocType.STRATEGY_STATE]: 'STRATEGY_STATE',
+  [DocType.USER_OUTCOME]: 'USER_OUTCOME',
+  [DocType.STRATEGY_LEARNING_STATE]: 'STRATEGY_LEARNING_STATE',
 } as const;
 
 export interface CardHistory<T extends CardRecord> {

package/src/core/types/userOutcome.ts

@@ -0,0 +1,51 @@
+import { DocType } from './types-legacy';
+
+/**
+ * Record of a user's learning outcome over a specific period.
+ *
+ * Used by the evolutionary orchestration system to correlate strategy
+ * deviations with learning success.
+ * 
+ * Stored in the UserDB.
+ */
+export interface UserOutcomeRecord {
+  /** 
+   * Unique ID: "USER_OUTCOME::{courseId}::{userId}::{timestamp}" 
+   * Timestamp corresponds to periodEnd.
+   */
+  _id: string;
+  
+  docType: DocType.USER_OUTCOME;
+
+  courseId: string;
+  userId: string;
+
+  /** Start of the measurement period (ISO timestamp) */
+  periodStart: string;
+  /** End of the measurement period (ISO timestamp) */
+  periodEnd: string;
+
+  /**
+   * The computed signal value (e.g., 0.85 for 85% accuracy).
+   * This is the 'Y' in the regression analysis.
+   * 
+   * Higher values indicate better learning outcomes.
+   */
+  outcomeValue: number;
+
+  /**
+   * Snapshot of active deviations during this period.
+   * Maps strategyId -> deviation value used [-1.0, 1.0].
+   * This provides the 'X' values for regression analysis.
+   */
+  deviations: Record<string, number>;
+
+  metadata: {
+    sessionsCount: number;
+    cardsSeen: number;
+    eloStart: number;
+    eloEnd: number;
+    /** The algorithm used to compute outcomeValue (e.g. "accuracy_in_zone") */
+    signalType: string;
+  };
+}