@holoscript/framework 6.0.3 → 6.0.4

package/src/training/training/__tests__/TrainingPipelineConfig.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect } from 'vitest';
+import {
+  DEFAULT_TRAINING_PIPELINE_CONFIG,
+  buildTrainingPipelineConfig,
+  computeTotalSteps,
+} from '../TrainingPipelineConfig';
+import type { TrainingPipelineConfig } from '../TrainingPipelineConfig';
+import { DEFAULT_SOFTDEDUP_CONFIG } from '../SoftDedup';
+import { DEFAULT_LR_SCHEDULER_CONFIG } from '../LRScheduler';
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('TrainingPipelineConfig', () => {
+  // ---------------------------------------------------------------------------
+  // DEFAULT CONFIG
+  // ---------------------------------------------------------------------------
+
+  describe('DEFAULT_TRAINING_PIPELINE_CONFIG', () => {
+    it('has correct hyperparameters per W.006', () => {
+      const { hyperparameters } = DEFAULT_TRAINING_PIPELINE_CONFIG;
+
+      expect(hyperparameters.learningRate).toBe(2e-4); // NOT 2e-5
+      expect(hyperparameters.epochs).toBe(2); // NOT 3
+      expect(hyperparameters.optimizer).toBe('paged_adamw_8bit'); // NOT adamw_torch
+    });
+
+    it('has correct batch settings per W.007', () => {
+      const { hyperparameters } = DEFAULT_TRAINING_PIPELINE_CONFIG;
+
+      expect(hyperparameters.microBatchSize).toBe(8);
+      expect(hyperparameters.gradientAccumulationSteps).toBe(4);
+      // Effective batch = 8 * 4 = 32 (in range 32-512)
+      const effectiveBatch =
+        hyperparameters.microBatchSize * hyperparameters.gradientAccumulationSteps;
+      expect(effectiveBatch).toBeGreaterThanOrEqual(32);
+      expect(effectiveBatch).toBeLessThanOrEqual(512);
+    });
+
+    it('includes SoftDedup defaults (W.008)', () => {
+      expect(DEFAULT_TRAINING_PIPELINE_CONFIG.softDedup).toEqual(DEFAULT_SOFTDEDUP_CONFIG);
+    });
+
+    it('includes LR schedule defaults (W.009)', () => {
+      expect(DEFAULT_TRAINING_PIPELINE_CONFIG.lrSchedule).toEqual(DEFAULT_LR_SCHEDULER_CONFIG);
+    });
+
+    it('enables all pipeline stages by default', () => {
+      const { pipeline } = DEFAULT_TRAINING_PIPELINE_CONFIG;
+
+      expect(pipeline.enableQualityFilter).toBe(true);
+      expect(pipeline.enableSoftDedup).toBe(true);
+      expect(pipeline.enableLRSchedule).toBe(true);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // BUILD CONFIG
+  // ---------------------------------------------------------------------------
+
+  describe('buildTrainingPipelineConfig', () => {
+    it('returns defaults with no overrides', () => {
+      const config = buildTrainingPipelineConfig();
+      expect(config.hyperparameters.learningRate).toBe(
+        DEFAULT_TRAINING_PIPELINE_CONFIG.hyperparameters.learningRate
+      );
+    });
+
+    it('allows overriding hyperparameters', () => {
+      const config = buildTrainingPipelineConfig({
+        hyperparameters: { learningRate: 1e-4, epochs: 3 },
+      });
+
+      expect(config.hyperparameters.learningRate).toBe(1e-4);
+      expect(config.hyperparameters.epochs).toBe(3);
+      expect(config.hyperparameters.optimizer).toBe('paged_adamw_8bit'); // preserved
+    });
+
+    it('allows overriding softDedup settings', () => {
+      const config = buildTrainingPipelineConfig({
+        softDedup: { temperature: 0.5, wordLevel: true },
+      });
+
+      expect(config.softDedup.temperature).toBe(0.5);
+      expect(config.softDedup.wordLevel).toBe(true);
+      expect(config.softDedup.minWeight).toBe(DEFAULT_SOFTDEDUP_CONFIG.minWeight); // preserved
+    });
+
+    it('allows overriding lrSchedule settings', () => {
+      const config = buildTrainingPipelineConfig({
+        lrSchedule: { totalSteps: 5000, warmupRatio: 0.05 },
+      });
+
+      expect(config.lrSchedule.totalSteps).toBe(5000);
+      expect(config.lrSchedule.warmupRatio).toBe(0.05);
+      expect(config.lrSchedule.baseLR).toBe(DEFAULT_LR_SCHEDULER_CONFIG.baseLR); // preserved
+    });
+
+    it('allows disabling pipeline stages', () => {
+      const config = buildTrainingPipelineConfig({
+        pipeline: {
+          enableQualityFilter: false,
+          enableSoftDedup: false,
+          enableLRSchedule: false,
+        },
+      });
+
+      expect(config.pipeline.enableQualityFilter).toBe(false);
+      expect(config.pipeline.enableSoftDedup).toBe(false);
+      expect(config.pipeline.enableLRSchedule).toBe(false);
+    });
+
+    it('does not mutate the default config', () => {
+      const originalLR = DEFAULT_TRAINING_PIPELINE_CONFIG.hyperparameters.learningRate;
+      buildTrainingPipelineConfig({
+        hyperparameters: { learningRate: 999 },
+      });
+      expect(DEFAULT_TRAINING_PIPELINE_CONFIG.hyperparameters.learningRate).toBe(originalLR);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // COMPUTE TOTAL STEPS
+  // ---------------------------------------------------------------------------
+
+  describe('computeTotalSteps', () => {
+    it('computes correct steps for standard config', () => {
+      const config = buildTrainingPipelineConfig();
+      // Dataset: 920K, microBatch: 8, gradAccum: 4, epochs: 2
+      // effectiveBatch = 32
+      // stepsPerEpoch = ceil(920000 / 32) = 28750
+      // totalSteps = 28750 * 2 = 57500
+      const steps = computeTotalSteps(920000, config);
+      expect(steps).toBe(57500);
+    });
+
+    it('handles small datasets', () => {
+      const config = buildTrainingPipelineConfig({
+        hyperparameters: {
+          microBatchSize: 4,
+          gradientAccumulationSteps: 2,
+          epochs: 1,
+        },
+      });
+      // effectiveBatch = 8
+      // stepsPerEpoch = ceil(10 / 8) = 2
+      // totalSteps = 2 * 1 = 2
+      const steps = computeTotalSteps(10, config);
+      expect(steps).toBe(2);
+    });
+
+    it('handles dataset size of 1', () => {
+      const config = buildTrainingPipelineConfig({
+        hyperparameters: {
+          microBatchSize: 8,
+          gradientAccumulationSteps: 4,
+          epochs: 2,
+        },
+      });
+      // effectiveBatch = 32
+      // stepsPerEpoch = ceil(1 / 32) = 1
+      // totalSteps = 1 * 2 = 2
+      const steps = computeTotalSteps(1, config);
+      expect(steps).toBe(2);
+    });
+
+    it('handles dataset size of 0', () => {
+      const config = buildTrainingPipelineConfig();
+      const steps = computeTotalSteps(0, config);
+      expect(steps).toBe(0);
+    });
+
+    it('rounds up partial batches', () => {
+      const config = buildTrainingPipelineConfig({
+        hyperparameters: {
+          microBatchSize: 10,
+          gradientAccumulationSteps: 1,
+          epochs: 1,
+        },
+      });
+      // effectiveBatch = 10
+      // stepsPerEpoch = ceil(15 / 10) = 2
+      const steps = computeTotalSteps(15, config);
+      expect(steps).toBe(2);
+    });
+
+    it('scales linearly with epochs', () => {
+      const config1 = buildTrainingPipelineConfig({
+        hyperparameters: { epochs: 1 },
+      });
+      const config2 = buildTrainingPipelineConfig({
+        hyperparameters: { epochs: 2 },
+      });
+
+      const steps1 = computeTotalSteps(1000, config1);
+      const steps2 = computeTotalSteps(1000, config2);
+
+      expect(steps2).toBe(steps1 * 2);
+    });
+  });
+});

package/src/training/training/__tests__/schema.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Training Schema Tests
+ *
+ * Gap 1: Validates training example schema and validation functions.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { validateTrainingExample } from '../schema';
+import type { TrainingExample } from '../schema';
+
+describe('validateTrainingExample', () => {
+  const validExample: TrainingExample = {
+    instruction: 'Create a grabbable cube',
+    input: '',
+    output: 'object "Cube" @grabbable { position: [0,1,0] }',
+    metadata: {
+      category: 'vr-interaction',
+      difficulty: 'beginner',
+      traits: ['grabbable'],
+      keywords: ['vr', 'interaction'],
+      version: '6.0.0',
+    },
+  };
+
+  it('validates a correct training example', () => {
+    const result = validateTrainingExample(validExample);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('rejects null input', () => {
+    const result = validateTrainingExample(null);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].field).toBe('root');
+  });
+
+  it('rejects missing instruction', () => {
+    const result = validateTrainingExample({
+      ...validExample,
+      instruction: '',
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.field === 'instruction')).toBe(true);
+  });
+
+  it('rejects missing output', () => {
+    const result = validateTrainingExample({
+      ...validExample,
+      output: '',
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.field === 'output')).toBe(true);
+  });
+
+  it('rejects missing metadata', () => {
+    const { metadata, ...noMeta } = validExample;
+    const result = validateTrainingExample(noMeta);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.field === 'metadata')).toBe(true);
+  });
+
+  it('warns about missing traits array', () => {
+    const result = validateTrainingExample({
+      ...validExample,
+      metadata: {
+        ...validExample.metadata,
+        traits: 'not-an-array' as any,
+      },
+    });
+    expect(result.warnings.length).toBeGreaterThan(0);
+  });
+});

package/src/training/training/__tests__/training-constants.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Training Constants Tests
+ *
+ * Gap 1: Verifies canonical constants, type narrowing, and exhaustiveness.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  TRAINING_CATEGORIES,
+  DIFFICULTY_LEVELS,
+  QUALITY_THRESHOLDS,
+  DEFAULT_GENERATOR_THRESHOLDS,
+  RULEFORGE_DOMAINS,
+  getQualityTier,
+  isValidCategory,
+  isValidDifficulty,
+} from '../constants';
+
+describe('Training Constants', () => {
+  it('has 9 training categories', () => {
+    expect(TRAINING_CATEGORIES).toHaveLength(9);
+    expect(TRAINING_CATEGORIES).toContain('vr-interaction');
+    expect(TRAINING_CATEGORIES).toContain('ai-agents');
+    expect(TRAINING_CATEGORIES).toContain('physics');
+    expect(TRAINING_CATEGORIES).toContain('game-mechanics');
+  });
+
+  it('has 4 difficulty levels', () => {
+    expect(DIFFICULTY_LEVELS).toHaveLength(4);
+    expect(DIFFICULTY_LEVELS).toContain('beginner');
+    expect(DIFFICULTY_LEVELS).toContain('intermediate');
+    expect(DIFFICULTY_LEVELS).toContain('advanced');
+    expect(DIFFICULTY_LEVELS).toContain('production');
+  });
+
+  it('has quality thresholds with correct ranges', () => {
+    expect(QUALITY_THRESHOLDS.Excellent.min).toBe(90);
+    expect(QUALITY_THRESHOLDS.Excellent.max).toBe(100);
+    expect(QUALITY_THRESHOLDS.VeryGood.min).toBe(80);
+    expect(QUALITY_THRESHOLDS.VeryGood.max).toBe(89);
+    expect(QUALITY_THRESHOLDS.Acceptable.min).toBe(70);
+    expect(QUALITY_THRESHOLDS.Acceptable.max).toBe(79);
+  });
+
+  it('has default generator thresholds', () => {
+    expect(DEFAULT_GENERATOR_THRESHOLDS.min_compression_ratio).toBe(5);
+    expect(DEFAULT_GENERATOR_THRESHOLDS.max_duplication_rate).toBe(0.05);
+    expect(DEFAULT_GENERATOR_THRESHOLDS.min_quality_score).toBe(0.7);
+  });
+
+  it('has 8 ruleforge domains', () => {
+    expect(RULEFORGE_DOMAINS).toHaveLength(8);
+    expect(RULEFORGE_DOMAINS).toContain('ai_agents');
+    expect(RULEFORGE_DOMAINS).toContain('physics');
+  });
+});
+
+describe('getQualityTier', () => {
+  it('returns Excellent for scores >= 90', () => {
+    expect(getQualityTier(95)).toBe('Excellent');
+    expect(getQualityTier(90)).toBe('Excellent');
+    expect(getQualityTier(100)).toBe('Excellent');
+  });
+
+  it('returns VeryGood for scores 80-89', () => {
+    expect(getQualityTier(85)).toBe('VeryGood');
+    expect(getQualityTier(80)).toBe('VeryGood');
+    expect(getQualityTier(89)).toBe('VeryGood');
+  });
+
+  it('returns Acceptable for scores 70-79', () => {
+    expect(getQualityTier(75)).toBe('Acceptable');
+    expect(getQualityTier(70)).toBe('Acceptable');
+    expect(getQualityTier(79)).toBe('Acceptable');
+  });
+
+  it('returns BelowAcceptable for scores < 70', () => {
+    expect(getQualityTier(69)).toBe('BelowAcceptable');
+    expect(getQualityTier(0)).toBe('BelowAcceptable');
+    expect(getQualityTier(50)).toBe('BelowAcceptable');
+  });
+});
+
+describe('isValidCategory', () => {
+  it('validates known categories', () => {
+    expect(isValidCategory('physics')).toBe(true);
+    expect(isValidCategory('ai-agents')).toBe(true);
+  });
+
+  it('rejects unknown categories', () => {
+    expect(isValidCategory('unknown')).toBe(false);
+    expect(isValidCategory('')).toBe(false);
+  });
+});
+
+describe('isValidDifficulty', () => {
+  it('validates known difficulties', () => {
+    expect(isValidDifficulty('beginner')).toBe(true);
+    expect(isValidDifficulty('production')).toBe(true);
+  });
+
+  it('rejects unknown difficulties', () => {
+    expect(isValidDifficulty('expert')).toBe(false);
+    expect(isValidDifficulty('')).toBe(false);
+  });
+});

package/src/training/training/__tests__/trait-mappings.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Trait Mappings Tests
+ *
+ * Gap 1 + 2: Validates TM-to-HS trait mapping and validation functions.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  TM_REGISTERED_TRAITS,
+  validateTraitName,
+  generateValidationReport,
+} from '../trait-mappings';
+
+describe('TM_REGISTERED_TRAITS', () => {
+  it('has 48 registered traits', () => {
+    expect(TM_REGISTERED_TRAITS).toHaveLength(48);
+  });
+
+  it('includes core VR traits', () => {
+    expect(TM_REGISTERED_TRAITS).toContain('grabbable');
+    expect(TM_REGISTERED_TRAITS).toContain('throwable');
+    expect(TM_REGISTERED_TRAITS).toContain('physics');
+  });
+
+  it('includes AI traits', () => {
+    expect(TM_REGISTERED_TRAITS).toContain('llm_agent');
+    expect(TM_REGISTERED_TRAITS).toContain('behavior_tree');
+  });
+});
+
+describe('validateTraitName', () => {
+  const validTraits = new Set(['grabbable', 'throwable', 'physics', 'networked']);
+
+  it('matches exact trait names', () => {
+    expect(validateTraitName('grabbable', validTraits)).toBe('grabbable');
+    expect(validateTraitName('physics', validTraits)).toBe('physics');
+  });
+
+  it('strips @ prefix and normalizes', () => {
+    expect(validateTraitName('@grabbable', validTraits)).toBe('grabbable');
+  });
+
+  it('returns null for unknown traits', () => {
+    expect(validateTraitName('unknown_trait', validTraits)).toBeNull();
+  });
+
+  it('works with readonly arrays', () => {
+    const arr = ['grabbable', 'physics'] as const;
+    expect(validateTraitName('grabbable', arr)).toBe('grabbable');
+  });
+});
+
+describe('generateValidationReport', () => {
+  const hsTraits = new Set(['grabbable', 'throwable', 'physics', 'networked', 'glowing']);
+  const deprecatedTraits = new Set(['collision', 'talkable']);
+
+  it('correctly classifies matched traits', () => {
+    const report = generateValidationReport(['grabbable', 'physics'], hsTraits);
+    expect(report.matched).toBe(2);
+    expect(report.unmatched).toBe(0);
+    expect(report.total).toBe(2);
+  });
+
+  it('correctly identifies unmatched traits', () => {
+    const report = generateValidationReport(['grabbable', 'unknown_trait'], hsTraits);
+    expect(report.matched).toBe(1);
+    expect(report.unmatched).toBe(1);
+  });
+
+  it('correctly identifies deprecated traits', () => {
+    const report = generateValidationReport(['collision', 'grabbable'], hsTraits, deprecatedTraits);
+    expect(report.deprecated).toBe(1);
+    expect(report.matched).toBe(1);
+  });
+
+  it('generates full report for TM traits', () => {
+    const report = generateValidationReport(TM_REGISTERED_TRAITS as unknown as string[], hsTraits);
+    expect(report.total).toBe(48);
+    expect(report.matched + report.unmatched + report.deprecated).toBe(48);
+  });
+});

package/src/training/training/constants.ts

@@ -0,0 +1,94 @@
+/**
+ * Training Constants
+ *
+ * Canonical constants shared between @holoscript/core and TrainingMonkey.
+ * This module has ZERO imports from other workspace packages (G.GAP.01 prevention).
+ *
+ * @version 1.0.0
+ */
+
+/**
+ * 9 training categories covering all HoloScript domains
+ */
+export const TRAINING_CATEGORIES = [
+  'vr-interaction',
+  'multiplayer',
+  'physics',
+  'ui-spatial',
+  'ai-agents',
+  'procedural',
+  'audio-spatial',
+  'visual-effects',
+  'game-mechanics',
+] as const;
+
+export type TrainingCategory = (typeof TRAINING_CATEGORIES)[number];
+
+/**
+ * 4 difficulty levels for training data
+ */
+export const DIFFICULTY_LEVELS = ['beginner', 'intermediate', 'advanced', 'production'] as const;
+
+export type DifficultyLevel = (typeof DIFFICULTY_LEVELS)[number];
+
+/**
+ * Quality score thresholds for training data evaluation
+ */
+export const QUALITY_THRESHOLDS = {
+  Excellent: { min: 90, max: 100 },
+  VeryGood: { min: 80, max: 89 },
+  Acceptable: { min: 70, max: 79 },
+} as const;
+
+export type QualityTier = keyof typeof QUALITY_THRESHOLDS;
+
+/**
+ * Default quality constraints for training data generators
+ */
+export const DEFAULT_GENERATOR_THRESHOLDS = {
+  min_compression_ratio: 5,
+  max_compression_ratio: 15,
+  max_duplication_rate: 0.05,
+  min_templates_per_difficulty: 10,
+  min_quality_score: 0.7,
+} as const;
+
+/**
+ * RuleForge domain categories used by the rule generator
+ */
+export const RULEFORGE_DOMAINS = [
+  'ai_agents',
+  'physics',
+  'robotics',
+  'audio',
+  'rendering',
+  'interaction',
+  'multiplayer',
+  'vr_ar',
+] as const;
+
+export type RuleForgeDomain = (typeof RULEFORGE_DOMAINS)[number];
+
+/**
+ * Get quality tier for a given score
+ */
+export function getQualityTier(score: number): QualityTier | 'BelowAcceptable' {
+  if (score >= QUALITY_THRESHOLDS.Excellent.min) return 'Excellent';
+  if (score >= QUALITY_THRESHOLDS.VeryGood.min) return 'VeryGood';
+  if (score >= QUALITY_THRESHOLDS.Acceptable.min) return 'Acceptable';
+  return 'BelowAcceptable';
+}
+
+/**
+ * Validate that a category string is a valid TrainingCategory
+ */
+export function isValidCategory(category: string): category is TrainingCategory {
+  return (TRAINING_CATEGORIES as readonly string[]).includes(category);
+}
+
+/**
+ * Validate that a difficulty string is a valid DifficultyLevel
+ */
+export function isValidDifficulty(difficulty: string): difficulty is DifficultyLevel {
+  return (DIFFICULTY_LEVELS as readonly string[]).includes(difficulty);
+}

package/src/training/training/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @holoscript/core - Training Module
+ *
+ * Spatial training data generation, sparsity monitoring, quality scoring,
+ * and training pipeline configuration.
+ */
+export * from './SparsityMonitor';
+export * from './SparsityMonitorTypes';
+export * from './SpatialTrainingDataGenerator';
+export * from './SpatialTrainingDataTypes';
+export * from './TrainingPipelineConfig';
+export * from './QualityScoringPipeline';
+export * from './SoftDedup';
+export * from './LRScheduler';
+export * from './constants';
+export * from './trait-mappings';
+export * from './schema';