@holoscript/framework 6.0.3

package/src/ai/__tests__/TrainingDataGenerator.test.ts

@@ -0,0 +1,286 @@
+import { describe, it, expect } from 'vitest';
+import {
+  TrainingDataGenerator,
+  createTrainingDataGenerator,
+  ALL_CATEGORIES,
+  type TrainingExample,
+  type TrainingCategory,
+} from '../TrainingDataGenerator';
+
+describe('TrainingDataGenerator', () => {
+  describe('initialization', () => {
+    it('should create generator', () => {
+      const generator = new TrainingDataGenerator();
+      expect(generator).toBeDefined();
+    });
+
+    it('should create generator via factory', () => {
+      const generator = createTrainingDataGenerator();
+      expect(generator).toBeDefined();
+    });
+  });
+
+  describe('generateAll', () => {
+    it('should return all examples', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.generateAll();
+
+      expect(examples.length).toBeGreaterThan(40);
+    });
+
+    it('should have required fields for each example', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.generateAll();
+
+      for (const ex of examples) {
+        expect(ex.id).toBeDefined();
+        expect(ex.category).toBeDefined();
+        expect(ex.description).toBeDefined();
+        expect(ex.holoScript).toBeDefined();
+        expect(ex.tags).toBeDefined();
+        expect(ex.complexity).toBeDefined();
+      }
+    });
+
+    it('should have valid HoloScript code', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.generateAll();
+
+      for (const ex of examples) {
+        expect(ex.holoScript.length).toBeGreaterThan(10);
+        // Should contain at least one keyword
+        const hasKeyword = ['object', 'composition', 'template', 'ui_', 'zone'].some((kw) =>
+          ex.holoScript.includes(kw)
+        );
+        expect(hasKeyword).toBe(true);
+      }
+    });
+  });
+
+  describe('generate with options', () => {
+    it('should filter by category', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.generate({ categories: ['geometry'] });
+
+      expect(examples.length).toBeGreaterThan(0);
+      for (const ex of examples) {
+        expect(ex.category).toBe('geometry');
+      }
+    });
+
+    it('should filter by multiple categories', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.generate({ categories: ['geometry', 'materials'] });
+
+      expect(examples.length).toBeGreaterThan(0);
+      for (const ex of examples) {
+        expect(['geometry', 'materials']).toContain(ex.category);
+      }
+    });
+
+    it('should filter by complexity', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.generate({ complexityFilter: ['basic'] });
+
+      expect(examples.length).toBeGreaterThan(0);
+      for (const ex of examples) {
+        expect(ex.complexity).toBe('basic');
+      }
+    });
+
+    it('should limit count', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.generate({ count: 5 });
+
+      expect(examples.length).toBe(5);
+    });
+
+    it('should combine filters', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.generate({
+        categories: ['physics'],
+        complexityFilter: ['basic', 'intermediate'],
+        count: 3,
+      });
+
+      expect(examples.length).toBeLessThanOrEqual(3);
+      for (const ex of examples) {
+        expect(ex.category).toBe('physics');
+        expect(['basic', 'intermediate']).toContain(ex.complexity);
+      }
+    });
+  });
+
+  describe('getByCategory', () => {
+    it('should return geometry examples', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.getByCategory('geometry');
+
+      expect(examples.length).toBeGreaterThan(5);
+      for (const ex of examples) {
+        expect(ex.category).toBe('geometry');
+      }
+    });
+
+    it('should return UI examples', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.getByCategory('ui');
+
+      expect(examples.length).toBeGreaterThan(3);
+    });
+
+    it('should return physics examples', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.getByCategory('physics');
+
+      expect(examples.length).toBeGreaterThan(3);
+    });
+  });
+
+  describe('getByComplexity', () => {
+    it('should return basic examples', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.getByComplexity('basic');
+
+      expect(examples.length).toBeGreaterThan(5);
+      for (const ex of examples) {
+        expect(ex.complexity).toBe('basic');
+      }
+    });
+
+    it('should return advanced examples', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.getByComplexity('advanced');
+
+      expect(examples.length).toBeGreaterThan(5);
+      for (const ex of examples) {
+        expect(ex.complexity).toBe('advanced');
+      }
+    });
+  });
+
+  describe('getByTag', () => {
+    it('should return examples by tag', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.getByTag('physics');
+
+      expect(examples.length).toBeGreaterThan(0);
+      for (const ex of examples) {
+        expect(ex.tags).toContain('physics');
+      }
+    });
+
+    it('should find VR-related examples', () => {
+      const generator = new TrainingDataGenerator();
+      const vrExamples = generator.getByTag('vr');
+
+      expect(vrExamples.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('getStats', () => {
+    it('should return category counts', () => {
+      const generator = new TrainingDataGenerator();
+      const stats = generator.getStats();
+
+      expect(stats.geometry).toBeGreaterThan(0);
+      expect(stats.materials).toBeGreaterThan(0);
+      expect(stats.physics).toBeGreaterThan(0);
+      expect(stats.interactions).toBeGreaterThan(0);
+    });
+
+    it('should have all categories represented', () => {
+      const generator = new TrainingDataGenerator();
+      const stats = generator.getStats();
+
+      const categories = Object.keys(stats);
+      expect(categories.length).toBeGreaterThanOrEqual(10);
+    });
+  });
+
+  describe('export', () => {
+    it('should export as JSON', () => {
+      const generator = new TrainingDataGenerator();
+      const json = generator.exportJSON();
+
+      expect(json).toBeDefined();
+      const parsed = JSON.parse(json);
+      expect(Array.isArray(parsed)).toBe(true);
+      expect(parsed.length).toBeGreaterThan(0);
+    });
+
+    it('should export as JSONL', () => {
+      const generator = new TrainingDataGenerator();
+      const jsonl = generator.exportJSONL();
+
+      expect(jsonl).toBeDefined();
+      const lines = jsonl.split('\n');
+      expect(lines.length).toBeGreaterThan(0);
+
+      // Each line should be valid JSON
+      for (const line of lines) {
+        expect(() => JSON.parse(line)).not.toThrow();
+      }
+    });
+  });
+
+  describe('ALL_CATEGORIES constant', () => {
+    it('should include all expected categories', () => {
+      expect(ALL_CATEGORIES).toContain('geometry');
+      expect(ALL_CATEGORIES).toContain('materials');
+      expect(ALL_CATEGORIES).toContain('physics');
+      expect(ALL_CATEGORIES).toContain('interactions');
+      expect(ALL_CATEGORIES).toContain('audio');
+      expect(ALL_CATEGORIES).toContain('ui');
+      expect(ALL_CATEGORIES).toContain('composition');
+      expect(ALL_CATEGORIES).toContain('state');
+      expect(ALL_CATEGORIES).toContain('logic');
+      expect(ALL_CATEGORIES).toContain('traits');
+      expect(ALL_CATEGORIES).toContain('animations');
+      expect(ALL_CATEGORIES).toContain('ar_vr');
+    });
+  });
+
+  describe('Example content quality', () => {
+    it('should have diverse examples for geometry', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.getByCategory('geometry');
+
+      const geometryTypes = new Set(
+        examples.map((ex) => {
+          const match = ex.holoScript.match(/geometry:\s*"(\w+)"/);
+          return match ? match[1] : null;
+        })
+      );
+
+      // Should have multiple geometry types
+      expect(geometryTypes.size).toBeGreaterThan(3);
+    });
+
+    it('should have examples with traits', () => {
+      const generator = new TrainingDataGenerator();
+      const allExamples = generator.generateAll();
+
+      const examplesWithTraits = allExamples.filter((ex) => ex.holoScript.includes('@'));
+      expect(examplesWithTraits.length).toBeGreaterThan(10);
+    });
+
+    it('should have examples with logic blocks', () => {
+      const generator = new TrainingDataGenerator();
+      const allExamples = generator.generateAll();
+
+      const examplesWithLogic = allExamples.filter((ex) => ex.holoScript.includes('logic {'));
+      expect(examplesWithLogic.length).toBeGreaterThan(5);
+    });
+
+    it('should have unique IDs', () => {
+      const generator = new TrainingDataGenerator();
+      const examples = generator.generateAll();
+
+      const ids = examples.map((ex) => ex.id);
+      const uniqueIds = new Set(ids);
+
+      expect(uniqueIds.size).toBe(ids.length);
+    });
+  });
+});

package/src/ai/__tests__/UtilityAI.prod.test.ts

@@ -0,0 +1,207 @@
+/**
+ * UtilityAI.prod.test.ts — Sprint CLXX
+ *
+ * Production edge-case integration tests for the Utility AI orchestrator.
+ * Ensures complex quadratic falloffs, dual-agent prioritization,
+ * cooldown evasion, and fuzzy logic integration correctness.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { UtilityAI } from '../UtilityAI';
+import type { UtilityAction, Consideration } from '../UtilityAI';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let ai: UtilityAI;
+let globalTime = 0;
+
+beforeEach(() => {
+  ai = new UtilityAI();
+  globalTime = 0;
+});
+
+function createAction(
+  id: string,
+  inputFn: () => number,
+  weight = 1.0,
+  cooldown = 0,
+  curve: 'linear' | 'quadratic' | 'logistic' | 'step' = 'linear'
+): UtilityAction {
+  return {
+    id,
+    name: id,
+    considerations: [
+      {
+        name: 'default',
+        input: inputFn,
+        curve,
+        weight,
+        invert: false,
+      },
+    ],
+    cooldown,
+    lastExecuted: -Infinity,
+    bonus: 0,
+    execute: () => {},
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('UtilityAI Complex Integration', () => {
+  it('handles 100 simultaneous actions, correctly prioritizing mathematically', () => {
+    for (let i = 0; i < 100; i++) {
+      ai.addAction(createAction(`action-${i}`, () => i / 100, 1.0));
+    }
+
+    // action-99 should have the highest score (99/100)
+    const best = ai.selectBest();
+    expect(best?.name).toBe('action-99');
+  });
+
+  it('quadratic score modifiers apply correctly over base weights', () => {
+    // Action A: Input 0.5, Weight 1.0, Quadratic -> Final: 1.0 * (0.5)^2 = 0.25
+    ai.addAction(createAction('A', () => 0.5, 1.0, 0, 'quadratic'));
+
+    // Action B: Input 0.4, Weight 2.0, Linear -> Final: 2.0 * 0.4 = 0.8
+    // Wait, earlier I assumed Weight * Input^2. Let's make B quadratic too.
+    // Action B: Input 0.4, Weight 2.0, Quadratic -> Final: 2.0 * (0.4)^2 = 0.32
+    ai.addAction(createAction('B', () => 0.4, 2.0, 0, 'quadratic'));
+
+    const best = ai.selectBest();
+    expect(best?.name).toBe('B'); // 0.32 > 0.25
+  });
+
+  it('returns null if all tasks score exactly 0', () => {
+    ai.addAction(createAction('A', () => 0));
+    ai.addAction(createAction('B', () => 0));
+    expect(ai.executeBest()).toBeNull();
+  });
+
+  it('dynamic context changes dynamically swap active action', () => {
+    let health = 100;
+    let enemyDistance = 50;
+
+    ai.addAction(createAction('attack', () => (100 - enemyDistance) / 100));
+    ai.addAction(createAction('heal', () => (100 - health) / 100));
+
+    // Enemy is 50m away (attack=0.5), health is full (heal=0.0). Attack!
+    expect(ai.selectBest()?.name).toBe('attack');
+
+    // Health drops to 10. Heal score = 0.9. Attack score = 0.5. Heal!
+    health = 10;
+    expect(ai.selectBest()?.name).toBe('heal');
+
+    // Enemy is 5m away (attack=0.95). Health is 30 (heal=0.7). Attack!
+    enemyDistance = 5;
+    health = 30;
+    expect(ai.selectBest()?.name).toBe('attack');
+  });
+
+  it('cooldown logic completely zeros out otherwise highly weighted actions', () => {
+    const ultimate = createAction('ultimate-attack', () => 1.0, 1.0, 5.0);
+    ai.addAction(ultimate);
+    ai.addAction(createAction('punch', () => 0.5));
+
+    // Ultimate is available and scores > 0
+    expect(ai.scoreAction(ultimate)).toBeGreaterThan(0);
+
+    // Execute ultimate
+    ai.setTime(0);
+    ai.executeBest();
+
+    // Now it is on cooldown
+    expect(ai.scoreAction(ultimate)).toBe(0);
+
+    // Wait 2 seconds (still on cooldown)
+    ai.setTime(2.0);
+    expect(ai.scoreAction(ultimate)).toBe(0);
+
+    // Wait 4 more seconds (2 + 4 = 6)
+    ai.setTime(6.0);
+    // Now it is off cooldown
+    expect(ai.scoreAction(ultimate)).toBeGreaterThan(0);
+  });
+
+  it('keeps running current action if its priority drops slightly but not below others', () => {
+    let runs = 0;
+    let scoreA = 0.9;
+
+    const actionA = createAction('A', () => scoreA);
+    actionA.execute = () => {
+      runs++;
+    };
+
+    ai.addAction(actionA);
+    ai.addAction(createAction('B', () => 0.5));
+
+    ai.executeBest();
+    expect(runs).toBe(1);
+
+    scoreA = 0.6; // Priority dropped, but still > 0.5
+    ai.executeBest();
+    expect(runs).toBe(2);
+  });
+
+  it('multiple considerations combine multiplicatively with flat bonus addition', () => {
+    const action = createAction('complex', () => 0);
+    action.considerations = [
+      { name: 'c1', input: () => 0.8, curve: 'linear', weight: 1.0, invert: false },
+      { name: 'c2', input: () => 0.5, curve: 'linear', weight: 2.0, invert: false },
+    ];
+    action.bonus = 0.2;
+    // Score should be: (0.8 * 1.0) * (0.5 * 2.0) + 0.2 =  0.8 * 1.0 + 0.2 = 1.0
+    // Wait, the formula is: score = 1. For each c: score *= c.value * c.weight
+    // So: score = 1 * (0.8 * 1.0) * (0.5 * 2.0) = 0.8. Total with bonus: 0.8 + 0.2 = 1.0
+    ai.addAction(action);
+
+    expect(ai.scoreAction(action)).toBeCloseTo(1.0);
+  });
+
+  it('logistic curve calculation correctness', () => {
+    const action = createAction('logistic', () => 0.5, 1.0, 0, 'logistic');
+    ai.addAction(action);
+
+    // logistic: 1 / (1 + Math.exp(-10 * (input - 0.5)))
+    // For input 0.5: 1 / (1 + exp(0)) = 0.5
+    expect(ai.scoreAction(action)).toBeCloseTo(0.5);
+
+    action.considerations[0].input = () => 1.0;
+    // For input 1.0: 1 / (1 + exp(-5)) ~ 0.9933
+    expect(ai.scoreAction(action)).toBeCloseTo(0.9933, 3);
+  });
+
+  it('step curve calculation correctness', () => {
+    const action = createAction('step', () => 0.49, 1.0, 0, 'step');
+    ai.addAction(action);
+    // < 0.5 = 0
+    expect(ai.scoreAction(action)).toBe(0);
+
+    // >= 0.5 returns 1.0
+    action.considerations[0].input = () => 0.5;
+    expect(ai.scoreAction(action)).toBe(1.0);
+  });
+
+  it('scoreAll returns correctly sorted array of scores', () => {
+    ai.addAction(createAction('C', () => 0.2));
+    ai.addAction(createAction('A', () => 0.8));
+    ai.addAction(createAction('B', () => 0.5));
+
+    const scores = ai.scoreAll();
+    expect(scores.length).toBe(3);
+    expect(scores[0].actionId).toBe('A');
+    expect(scores[1].actionId).toBe('B');
+    expect(scores[2].actionId).toBe('C');
+  });
+
+  it('executeBest handles no valid actions correctly', () => {
+    expect(ai.executeBest()).toBeNull();
+
+    ai.addAction(createAction('A', () => 0));
+    expect(ai.executeBest()).toBeNull();
+  });
+});

package/src/ai/__tests__/UtilityAI.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { UtilityAI, type UtilityAction, type Consideration } from '../UtilityAI';
+
+function makeAction(id: string, overrides: Partial<UtilityAction> = {}): UtilityAction {
+  return {
+    id,
+    name: id,
+    considerations: [{ name: 'always', input: () => 1, curve: 'linear', weight: 1, invert: false }],
+    cooldown: 0,
+    lastExecuted: -999,
+    bonus: 0,
+    execute: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe('UtilityAI', () => {
+  let ai: UtilityAI;
+
+  beforeEach(() => {
+    ai = new UtilityAI();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Action Management
+  // ---------------------------------------------------------------------------
+
+  it('addAction registers action', () => {
+    ai.addAction(makeAction('a'));
+    expect(ai.getActionCount()).toBe(1);
+  });
+
+  it('removeAction unregisters', () => {
+    ai.addAction(makeAction('a'));
+    ai.removeAction('a');
+    expect(ai.getActionCount()).toBe(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Scoring
+  // ---------------------------------------------------------------------------
+
+  it('scoreAction returns positive for available action', () => {
+    const act = makeAction('a');
+    ai.addAction(act);
+    expect(ai.scoreAction(act)).toBeGreaterThan(0);
+  });
+
+  it('scoreAction returns 0 during cooldown', () => {
+    const act = makeAction('a', { cooldown: 5, lastExecuted: 0 });
+    ai.addAction(act);
+    ai.setTime(2); // only 2s since lastExecuted, cooldown is 5
+    expect(ai.scoreAction(act)).toBe(0);
+  });
+
+  it('scoreAction applies quadratic curve', () => {
+    const c: Consideration = {
+      name: 'c',
+      input: () => 0.5,
+      curve: 'quadratic',
+      weight: 1,
+      invert: false,
+    };
+    const act = makeAction('a', { considerations: [c] });
+    ai.addAction(act);
+    expect(ai.scoreAction(act)).toBeCloseTo(0.25); // 0.5^2
+  });
+
+  it('scoreAction applies step curve', () => {
+    const cLow: Consideration = {
+      name: 'c',
+      input: () => 0.3,
+      curve: 'step',
+      weight: 1,
+      invert: false,
+    };
+    const cHigh: Consideration = {
+      name: 'c2',
+      input: () => 0.7,
+      curve: 'step',
+      weight: 1,
+      invert: false,
+    };
+    expect(ai.scoreAction(makeAction('lo', { considerations: [cLow] }))).toBe(0);
+    expect(ai.scoreAction(makeAction('hi', { considerations: [cHigh] }))).toBe(1);
+  });
+
+  it('scoreAction with invert flips input', () => {
+    const c: Consideration = {
+      name: 'c',
+      input: () => 0.2,
+      curve: 'linear',
+      weight: 1,
+      invert: true,
+    };
+    const act = makeAction('a', { considerations: [c] });
+    expect(ai.scoreAction(act)).toBeCloseTo(0.8);
+  });
+
+  it('scoreAction adds bonus', () => {
+    const act = makeAction('a', { bonus: 5 });
+    expect(ai.scoreAction(act)).toBe(6); // 1 (from consideration) + 5
+  });
+
+  // ---------------------------------------------------------------------------
+  // Score All
+  // ---------------------------------------------------------------------------
+
+  it('scoreAll returns sorted scores', () => {
+    ai.addAction(makeAction('low', { bonus: 0 }));
+    ai.addAction(makeAction('high', { bonus: 10 }));
+    const scores = ai.scoreAll();
+    expect(scores[0].actionId).toBe('high');
+    expect(scores[0].score).toBeGreaterThan(scores[1].score);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Selection & Execution
+  // ---------------------------------------------------------------------------
+
+  it('selectBest returns highest scored action', () => {
+    ai.addAction(makeAction('low', { bonus: 0 }));
+    ai.addAction(makeAction('high', { bonus: 10 }));
+    expect(ai.selectBest()!.id).toBe('high');
+  });
+
+  it('executeBest calls execute and returns id', () => {
+    const act = makeAction('a');
+    ai.addAction(act);
+    ai.setTime(10);
+    const result = ai.executeBest();
+    expect(result).toBe('a');
+    expect(act.execute).toHaveBeenCalledTimes(1);
+  });
+
+  it('executeBest returns null when all on cooldown', () => {
+    ai.addAction(makeAction('a', { cooldown: 100, lastExecuted: 0 }));
+    ai.setTime(1);
+    expect(ai.executeBest()).toBeNull();
+  });
+
+  // ---------------------------------------------------------------------------
+  // History
+  // ---------------------------------------------------------------------------
+
+  it('history records executed actions', () => {
+    ai.addAction(makeAction('a'));
+    ai.setTime(5);
+    ai.executeBest();
+    const hist = ai.getHistory();
+    expect(hist).toHaveLength(1);
+    expect(hist[0].actionId).toBe('a');
+    expect(hist[0].timestamp).toBe(5);
+  });
+});