@holoscript/framework 6.0.3

package/src/ai/UtilityAI.ts

@@ -0,0 +1,145 @@
+/**
+ * UtilityAI.ts
+ *
+ * Utility-based AI: action scoring with consideration curves,
+ * weighted selection, cooldowns, and action history.
+ *
+ * @module ai
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type CurveType = 'linear' | 'quadratic' | 'logistic' | 'step';
+
+export interface Consideration {
+  name: string;
+  input: () => number; // 0-1 normalized input
+  curve: CurveType;
+  weight: number;
+  invert: boolean;
+}
+
+export interface UtilityAction {
+  id: string;
+  name: string;
+  considerations: Consideration[];
+  cooldown: number; // Seconds
+  lastExecuted: number;
+  bonus: number; // Flat score bonus
+  execute: () => void;
+}
+
+// =============================================================================
+// UTILITY AI
+// =============================================================================
+
+export class UtilityAI {
+  private actions: Map<string, UtilityAction> = new Map();
+  private history: Array<{ actionId: string; score: number; timestamp: number }> = [];
+  private maxHistory = 50;
+  private currentTime = 0;
+
+  // ---------------------------------------------------------------------------
+  // Action Management
+  // ---------------------------------------------------------------------------
+
+  addAction(action: UtilityAction): void {
+    this.actions.set(action.id, action);
+  }
+  removeAction(id: string): void {
+    this.actions.delete(id);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Scoring
+  // ---------------------------------------------------------------------------
+
+  scoreAction(action: UtilityAction): number {
+    if (this.currentTime - action.lastExecuted < action.cooldown) return 0;
+
+    let score = 1;
+    for (const c of action.considerations) {
+      let input = Math.max(0, Math.min(1, c.input()));
+      if (c.invert) input = 1 - input;
+
+      let value: number;
+      switch (c.curve) {
+        case 'linear':
+          value = input;
+          break;
+        case 'quadratic':
+          value = input * input;
+          break;
+        case 'logistic':
+          value = 1 / (1 + Math.exp(-10 * (input - 0.5)));
+          break;
+        case 'step':
+          value = input >= 0.5 ? 1 : 0;
+          break;
+      }
+
+      score *= value * c.weight;
+    }
+
+    return score + action.bonus;
+  }
+
+  scoreAll(): Array<{ actionId: string; score: number }> {
+    const scores: Array<{ actionId: string; score: number }> = [];
+    for (const action of this.actions.values()) {
+      scores.push({ actionId: action.id, score: this.scoreAction(action) });
+    }
+    return scores.sort((a, b) => b.score - a.score);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Selection & Execution
+  // ---------------------------------------------------------------------------
+
+  selectBest(): UtilityAction | null {
+    let bestAction: UtilityAction | null = null;
+    let bestScore = -Infinity;
+
+    for (const action of this.actions.values()) {
+      const score = this.scoreAction(action);
+      if (score > bestScore) {
+        bestScore = score;
+        bestAction = action;
+      }
+    }
+
+    return bestAction;
+  }
+
+  executeBest(): string | null {
+    const action = this.selectBest();
+    if (!action || this.scoreAction(action) <= 0) return null;
+
+    action.execute();
+    action.lastExecuted = this.currentTime;
+    this.history.push({
+      actionId: action.id,
+      score: this.scoreAction(action),
+      timestamp: this.currentTime,
+    });
+    if (this.history.length > this.maxHistory) this.history.shift();
+
+    return action.id;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Time
+  // ---------------------------------------------------------------------------
+
+  setTime(time: number): void {
+    this.currentTime = time;
+  }
+  getHistory() {
+    return [...this.history];
+  }
+  getActionCount(): number {
+    return this.actions.size;
+  }
+}

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

@@ -0,0 +1,259 @@
+/**
+ * AIAdapter Registry — Production Tests
+ *
+ * Tests: registerAIAdapter, getAIAdapter, getDefaultAIAdapter,
+ * setDefaultAIAdapter, unregisterAIAdapter, listAIAdapters,
+ * and the convenience wrappers (generateHoloScript, explainHoloScript,
+ * optimizeHoloScript, fixHoloScript).
+ *
+ * Each test isolates registry state by registering unique IDs.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  registerAIAdapter,
+  getAIAdapter,
+  getDefaultAIAdapter,
+  setDefaultAIAdapter,
+  unregisterAIAdapter,
+  listAIAdapters,
+  generateHoloScript,
+  explainHoloScript,
+  optimizeHoloScript,
+  fixHoloScript,
+  type AIAdapter,
+  type GenerateResult,
+  type ExplainResult,
+  type OptimizeResult,
+  type FixResult,
+} from '../AIAdapter';
+
+let _counter = 0;
+function uniqueId(): string {
+  return `test-adapter-${_counter++}`;
+}
+
+function makeAdapter(overrides: Partial<AIAdapter> = {}): AIAdapter {
+  const id = uniqueId();
+  return {
+    id,
+    name: `Test Adapter ${id}`,
+    isReady: () => true,
+    generateHoloScript: async (prompt: string) =>
+      ({
+        holoScript: `object "Test" { // ${prompt} }`,
+        confidence: 0.9,
+      }) as GenerateResult,
+    explainHoloScript: async () => ({ explanation: 'This creates a cube.' }) as ExplainResult,
+    optimizeHoloScript: async (code: string) =>
+      ({
+        holoScript: code + ' // optimized',
+        improvements: ['removed redundant calls'],
+      }) as OptimizeResult,
+    fixHoloScript: async (code: string, errors: string[]) =>
+      ({
+        holoScript: code,
+        fixes: errors.map((e) => ({ line: 0, issue: e, fix: 'auto-fixed' })),
+      }) as FixResult,
+    ...overrides,
+  };
+}
+
+// --- registerAIAdapter / getAIAdapter ---
+describe('registerAIAdapter and getAIAdapter', () => {
+  it('retrieves a registered adapter by id', () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, false);
+    expect(getAIAdapter(a.id)).toBe(a);
+  });
+
+  it('returns undefined for unregistered id', () => {
+    expect(getAIAdapter('totally-unknown-99999')).toBeUndefined();
+  });
+
+  it('overwriting with same id replaces the adapter', () => {
+    const id = uniqueId();
+    const a1 = makeAdapter({ id, name: 'First' });
+    const a2 = makeAdapter({ id, name: 'Second' });
+    registerAIAdapter(a1, false);
+    registerAIAdapter(a2, false);
+    expect(getAIAdapter(id)!.name).toBe('Second');
+  });
+
+  it('multiple adapters can coexist', () => {
+    const a = makeAdapter();
+    const b = makeAdapter();
+    registerAIAdapter(a, false);
+    registerAIAdapter(b, false);
+    expect(getAIAdapter(a.id)).toBe(a);
+    expect(getAIAdapter(b.id)).toBe(b);
+  });
+});
+
+// --- default adapter ---
+describe('getDefaultAIAdapter / setDefaultAIAdapter', () => {
+  it('first registered adapter becomes default when setAsDefault=true', () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, true);
+    expect(getDefaultAIAdapter()).toBe(a);
+  });
+
+  it('setDefaultAIAdapter changes the default', () => {
+    const a = makeAdapter();
+    const b = makeAdapter();
+    registerAIAdapter(a, true);
+    registerAIAdapter(b, false);
+    const result = setDefaultAIAdapter(b.id);
+    expect(result).toBe(true);
+    expect(getDefaultAIAdapter()).toBe(b);
+  });
+
+  it('setDefaultAIAdapter returns false for unknown id', () => {
+    expect(setDefaultAIAdapter('nonexistent-id')).toBe(false);
+  });
+
+  it('setDefaultAIAdapter does not change default when id not found', () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, true);
+    setDefaultAIAdapter('nope');
+    expect(getDefaultAIAdapter()).toBe(a);
+  });
+});
+
+// --- unregisterAIAdapter ---
+describe('unregisterAIAdapter', () => {
+  it('removes adapter from registry', () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, false);
+    expect(unregisterAIAdapter(a.id)).toBe(true);
+    expect(getAIAdapter(a.id)).toBeUndefined();
+  });
+
+  it('returns false for unknown id', () => {
+    expect(unregisterAIAdapter('definitely-not-registered')).toBe(false);
+  });
+
+  it('removes adapter from listAIAdapters', () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, false);
+    unregisterAIAdapter(a.id);
+    const ids = listAIAdapters().map((x) => x.id);
+    expect(ids).not.toContain(a.id);
+  });
+
+  it('default falls back to another adapter when current default is removed', () => {
+    const a = makeAdapter();
+    const b = makeAdapter();
+    registerAIAdapter(a, true);
+    registerAIAdapter(b, false);
+    unregisterAIAdapter(a.id);
+    // Should fall back to some remaining adapter (not null if b is still registered)
+    const def = getDefaultAIAdapter();
+    expect(def === null || def!.id !== a.id).toBe(true);
+  });
+});
+
+// --- listAIAdapters ---
+describe('listAIAdapters', () => {
+  it('returns array with id and name for each adapter', () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, false);
+    const list = listAIAdapters();
+    const entry = list.find((x) => x.id === a.id);
+    expect(entry).toBeDefined();
+    expect(entry!.name).toBe(a.name);
+  });
+
+  it('each entry only has id and name (no extra methods)', () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, false);
+    const list = listAIAdapters();
+    const entry = list.find((x) => x.id === a.id)!;
+    expect(Object.keys(entry)).toEqual(['id', 'name']);
+  });
+});
+
+// --- generateHoloScript convenience wrapper ---
+describe('generateHoloScript (convenience)', () => {
+  it('delegates to default adapter', async () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, true);
+    const result = await generateHoloScript('a spinning cube');
+    expect(result.holoScript).toContain('Test');
+  });
+
+  it('throws when no adapter is registered', async () => {
+    // We cannot guarantee no adapter is registered in a shared module,
+    // so we test by expecting the resolved value to be defined only if adapter is set.
+    // Instead test the "no generate support" path:
+    const noGenAdapter = makeAdapter({ generateHoloScript: undefined });
+    registerAIAdapter(noGenAdapter, true);
+    await expect(generateHoloScript('test')).rejects.toThrow(/does not support generateHoloScript/);
+  });
+});
+
+// --- explainHoloScript convenience wrapper ---
+describe('explainHoloScript (convenience)', () => {
+  it('delegates to default adapter', async () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, true);
+    const result = await explainHoloScript('object "Cube" {}');
+    expect(result.explanation).toContain('cube');
+  });
+
+  it('throws when adapter does not support explain', async () => {
+    const noExplain = makeAdapter({ explainHoloScript: undefined });
+    registerAIAdapter(noExplain, true);
+    await expect(explainHoloScript('object "X" {}')).rejects.toThrow(
+      /does not support explainHoloScript/
+    );
+  });
+});
+
+// --- optimizeHoloScript convenience wrapper ---
+describe('optimizeHoloScript (convenience)', () => {
+  it('delegates to default adapter', async () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, true);
+    const result = await optimizeHoloScript('object "X" {}', 'mobile');
+    expect(result.improvements.length).toBeGreaterThan(0);
+  });
+
+  it('throws when adapter does not support optimize', async () => {
+    const noOpt = makeAdapter({ optimizeHoloScript: undefined });
+    registerAIAdapter(noOpt, true);
+    await expect(optimizeHoloScript('code', 'vr')).rejects.toThrow(
+      /does not support optimizeHoloScript/
+    );
+  });
+});
+
+// --- fixHoloScript convenience wrapper ---
+describe('fixHoloScript (convenience)', () => {
+  it('delegates to default adapter', async () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, true);
+    const result = await fixHoloScript('object "X" {}', ['missing brace', 'unknown property']);
+    expect(result.fixes).toHaveLength(2);
+    expect(result.fixes[0].fix).toBe('auto-fixed');
+  });
+
+  it('throws when adapter does not support fix', async () => {
+    const noFix = makeAdapter({ fixHoloScript: undefined });
+    registerAIAdapter(noFix, true);
+    await expect(fixHoloScript('code', ['err'])).rejects.toThrow(/does not support fixHoloScript/);
+  });
+
+  it('fix result has correct structure', async () => {
+    const a = makeAdapter();
+    registerAIAdapter(a, true);
+    const result = await fixHoloScript('code', ['err1', 'err2', 'err3']);
+    expect(result.holoScript).toBeTruthy();
+    expect(Array.isArray(result.fixes)).toBe(true);
+    for (const fix of result.fixes) {
+      expect(typeof fix.line).toBe('number');
+      expect(typeof fix.issue).toBe('string');
+      expect(typeof fix.fix).toBe('string');
+    }
+  });
+});

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

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  registerAIAdapter,
+  getAIAdapter,
+  getDefaultAIAdapter,
+  setDefaultAIAdapter,
+  listAIAdapters,
+  unregisterAIAdapter,
+  generateHoloScript,
+  explainHoloScript,
+  type AIAdapter,
+} from '../AIAdapter';
+
+function mockAdapter(id: string, name = id): AIAdapter {
+  return {
+    id,
+    name,
+    isReady: () => true,
+  };
+}
+
+// The registry uses module-level state, so we need to clean up
+function clearRegistry() {
+  for (const a of listAIAdapters()) {
+    unregisterAIAdapter(a.id);
+  }
+}
+
+describe('AIAdapter Registry', () => {
+  beforeEach(() => {
+    clearRegistry();
+  });
+
+  it('registerAIAdapter stores adapter', () => {
+    registerAIAdapter(mockAdapter('test'));
+    expect(getAIAdapter('test')).toBeDefined();
+  });
+
+  it('first registered becomes default', () => {
+    registerAIAdapter(mockAdapter('a'));
+    expect(getDefaultAIAdapter()?.id).toBe('a');
+  });
+
+  it('setAsDefault overrides default', () => {
+    registerAIAdapter(mockAdapter('a'));
+    registerAIAdapter(mockAdapter('b'), true);
+    expect(getDefaultAIAdapter()?.id).toBe('b');
+  });
+
+  it('getAIAdapter returns undefined for missing', () => {
+    expect(getAIAdapter('nope')).toBeUndefined();
+  });
+
+  it('setDefaultAIAdapter by id', () => {
+    registerAIAdapter(mockAdapter('a'));
+    registerAIAdapter(mockAdapter('b'));
+    expect(setDefaultAIAdapter('a')).toBe(true);
+    expect(getDefaultAIAdapter()?.id).toBe('a');
+  });
+
+  it('setDefaultAIAdapter returns false for missing', () => {
+    expect(setDefaultAIAdapter('nope')).toBe(false);
+  });
+
+  it('listAIAdapters returns all', () => {
+    registerAIAdapter(mockAdapter('a', 'Alpha'));
+    registerAIAdapter(mockAdapter('b', 'Beta'));
+    const list = listAIAdapters();
+    expect(list).toHaveLength(2);
+    expect(list.map((l) => l.id)).toContain('a');
+  });
+
+  it('unregisterAIAdapter removes adapter', () => {
+    registerAIAdapter(mockAdapter('a'));
+    expect(unregisterAIAdapter('a')).toBe(true);
+    expect(getAIAdapter('a')).toBeUndefined();
+  });
+
+  it('unregisterAIAdapter returns false for missing', () => {
+    expect(unregisterAIAdapter('nope')).toBe(false);
+  });
+
+  it('unregister default promotes next', () => {
+    registerAIAdapter(mockAdapter('a'));
+    registerAIAdapter(mockAdapter('b'));
+    unregisterAIAdapter('a');
+    expect(getDefaultAIAdapter()?.id).toBe('b');
+  });
+
+  it('unregister all sets default to null', () => {
+    registerAIAdapter(mockAdapter('a'));
+    unregisterAIAdapter('a');
+    expect(getDefaultAIAdapter()).toBeNull();
+  });
+
+  // --- Convenience functions ---
+  it('generateHoloScript throws without adapter', async () => {
+    await expect(generateHoloScript('test')).rejects.toThrow('No AI adapter registered');
+  });
+
+  it('generateHoloScript throws if adapter lacks method', async () => {
+    registerAIAdapter(mockAdapter('a'));
+    await expect(generateHoloScript('test')).rejects.toThrow('does not support');
+  });
+
+  it('explainHoloScript throws without adapter', async () => {
+    await expect(explainHoloScript('code')).rejects.toThrow('No AI adapter registered');
+  });
+});