@holoscript/framework 6.0.3

package/src/ai/AIAdapter.ts

@@ -0,0 +1,313 @@
+/**
+ * @holoscript/core AI Adapter Interface
+ *
+ * Provider-agnostic AI integration for HoloScript.
+ * Users can implement this interface to integrate any AI service.
+ *
+ * @example
+ * ```typescript
+ * import { AIAdapter, registerAIAdapter } from '@holoscript/core';
+ *
+ * // Implement your own adapter
+ * class MyOpenAIAdapter implements AIAdapter {
+ *   async generateHoloScript(prompt: string) {
+ *     const response = await openai.chat.completions.create({...});
+ *     return { holoScript: response.choices[0].message.content };
+ *   }
+ * }
+ *
+ * // Register it
+ * registerAIAdapter(new MyOpenAIAdapter());
+ * ```
+ */
+
+// ============================================================================
+// Core AI Adapter Interface
+// ============================================================================
+
+/**
+ * Result of HoloScript generation from natural language
+ */
+export interface GenerateResult {
+  /** Generated HoloScript code */
+  holoScript: string;
+  /** Confidence score (0-1) */
+  confidence?: number;
+  /** Estimated object count */
+  objectCount?: number;
+  /** Any warnings or suggestions */
+  warnings?: string[];
+  /** Provider-specific metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of HoloScript explanation
+ */
+export interface ExplainResult {
+  /** Human-readable explanation */
+  explanation: string;
+  /** Line-by-line breakdown */
+  breakdown?: Array<{
+    line: number;
+    code: string;
+    description: string;
+  }>;
+}
+
+/**
+ * Result of HoloScript optimization
+ */
+export interface OptimizeResult {
+  /** Optimized HoloScript code */
+  holoScript: string;
+  /** What was improved */
+  improvements: string[];
+  /** Performance metrics comparison */
+  metrics?: {
+    before: { polygons?: number; nodes?: number };
+    after: { polygons?: number; nodes?: number };
+  };
+}
+
+/**
+ * Result of HoloScript validation/fixing
+ */
+export interface FixResult {
+  /** Fixed HoloScript code */
+  holoScript: string;
+  /** Issues that were fixed */
+  fixes: Array<{
+    line: number;
+    issue: string;
+    fix: string;
+  }>;
+  /** Issues that couldn't be fixed automatically */
+  remaining?: string[];
+}
+
+/**
+ * Generation options
+ */
+export interface GenerateOptions {
+  /** Style hint: modern, classic, minimal, realistic */
+  style?: 'modern' | 'classic' | 'minimal' | 'realistic';
+  /** Complexity level */
+  complexity?: 'low' | 'medium' | 'high';
+  /** Include physics simulation */
+  includePhysics?: boolean;
+  /** Target platform for optimization */
+  targetPlatform?: 'mobile' | 'desktop' | 'vr' | 'ar';
+  /** Maximum tokens/length */
+  maxTokens?: number;
+  /** Temperature for generation (0-1) */
+  temperature?: number;
+  /** Additional context about the world */
+  context?: string;
+}
+
+/**
+ * AI Adapter Interface
+ *
+ * Implement this interface to integrate any AI provider with HoloScript.
+ * All methods are optional - implement only what your provider supports.
+ */
+export interface AIAdapter {
+  /** Unique identifier for this adapter */
+  readonly id: string;
+
+  /** Human-readable name */
+  readonly name: string;
+
+  /** Whether the adapter is ready to use */
+  isReady(): boolean | Promise<boolean>;
+
+  /**
+   * Generate HoloScript from natural language
+   * @param prompt User's natural language description
+   * @param options Generation options
+   */
+  generateHoloScript?(prompt: string, options?: GenerateOptions): Promise<GenerateResult>;
+
+  /**
+   * Explain what HoloScript code does
+   * @param holoScript The code to explain
+   */
+  explainHoloScript?(holoScript: string): Promise<ExplainResult>;
+
+  /**
+   * Optimize HoloScript for a target platform
+   * @param holoScript The code to optimize
+   * @param target Target platform
+   */
+  optimizeHoloScript?(
+    holoScript: string,
+    target: 'mobile' | 'desktop' | 'vr' | 'ar'
+  ): Promise<OptimizeResult>;
+
+  /**
+   * Fix errors in HoloScript code
+   * @param holoScript The code to fix
+   * @param errors Error messages from parser/validator
+   */
+  fixHoloScript?(holoScript: string, errors: string[]): Promise<FixResult>;
+
+  /**
+   * Complete HoloScript code (autocomplete)
+   * @param holoScript Partial code
+   * @param cursorPosition Position of cursor
+   */
+  completeHoloScript?(holoScript: string, cursorPosition: number): Promise<string[]>;
+
+  /**
+   * Chat with AI about HoloScript code
+   * @param message User message
+   * @param holoScript Current code context
+   * @param history Previous messages
+   */
+  chat?(
+    message: string,
+    holoScript?: string,
+    history?: Array<{ role: 'user' | 'assistant'; content: string }>
+  ): Promise<string>;
+
+  /**
+   * Get vector embeddings for text
+   * @param text Text to embed
+   */
+  getEmbeddings?(text: string | string[]): Promise<number[][]>;
+}
+
+// ============================================================================
+// Adapter Registry
+// ============================================================================
+
+let _defaultAdapter: AIAdapter | null = null;
+const _adapters = new Map<string, AIAdapter>();
+
+/**
+ * Register an AI adapter
+ * @param adapter The adapter to register
+ * @param setAsDefault Whether to set as the default adapter
+ */
+export function registerAIAdapter(adapter: AIAdapter, setAsDefault = false): void {
+  _adapters.set(adapter.id, adapter);
+  if (setAsDefault || _defaultAdapter === null) {
+    _defaultAdapter = adapter;
+  }
+}
+
+/**
+ * Get an AI adapter by ID
+ * @param id Adapter ID
+ */
+export function getAIAdapter(id: string): AIAdapter | undefined {
+  return _adapters.get(id);
+}
+
+/**
+ * Get the default AI adapter
+ */
+export function getDefaultAIAdapter(): AIAdapter | null {
+  return _defaultAdapter;
+}
+
+/**
+ * Set the default AI adapter
+ * @param id Adapter ID
+ */
+export function setDefaultAIAdapter(id: string): boolean {
+  const adapter = _adapters.get(id);
+  if (adapter) {
+    _defaultAdapter = adapter;
+    return true;
+  }
+  return false;
+}
+
+/**
+ * List all registered adapters
+ */
+export function listAIAdapters(): Array<{ id: string; name: string }> {
+  return Array.from(_adapters.values()).map((a) => ({
+    id: a.id,
+    name: a.name,
+  }));
+}
+
+/**
+ * Unregister an AI adapter
+ * @param id Adapter ID
+ */
+export function unregisterAIAdapter(id: string): boolean {
+  const deleted = _adapters.delete(id);
+  if (deleted && _defaultAdapter?.id === id) {
+    const firstAdapter = _adapters.values().next().value;
+    _defaultAdapter = firstAdapter ?? null;
+  }
+  return deleted;
+}
+
+// ============================================================================
+// Convenience Functions (use default adapter)
+// ============================================================================
+
+/**
+ * Generate HoloScript from natural language using the default adapter
+ */
+export async function generateHoloScript(
+  prompt: string,
+  options?: GenerateOptions
+): Promise<GenerateResult> {
+  if (!_defaultAdapter) {
+    throw new Error(
+      'No AI adapter registered. Call registerAIAdapter() first or use @holoscript/infinityassistant for Infinity Assistant integration.'
+    );
+  }
+  if (!_defaultAdapter.generateHoloScript) {
+    throw new Error(`AI adapter "${_defaultAdapter.name}" does not support generateHoloScript`);
+  }
+  return _defaultAdapter.generateHoloScript(prompt, options);
+}
+
+/**
+ * Explain HoloScript code using the default adapter
+ */
+export async function explainHoloScript(holoScript: string): Promise<ExplainResult> {
+  if (!_defaultAdapter) {
+    throw new Error('No AI adapter registered.');
+  }
+  if (!_defaultAdapter.explainHoloScript) {
+    throw new Error(`AI adapter "${_defaultAdapter.name}" does not support explainHoloScript`);
+  }
+  return _defaultAdapter.explainHoloScript(holoScript);
+}
+
+/**
+ * Optimize HoloScript using the default adapter
+ */
+export async function optimizeHoloScript(
+  holoScript: string,
+  target: 'mobile' | 'desktop' | 'vr' | 'ar'
+): Promise<OptimizeResult> {
+  if (!_defaultAdapter) {
+    throw new Error('No AI adapter registered.');
+  }
+  if (!_defaultAdapter.optimizeHoloScript) {
+    throw new Error(`AI adapter "${_defaultAdapter.name}" does not support optimizeHoloScript`);
+  }
+  return _defaultAdapter.optimizeHoloScript(holoScript, target);
+}
+
+/**
+ * Fix HoloScript errors using the default adapter
+ */
+export async function fixHoloScript(holoScript: string, errors: string[]): Promise<FixResult> {
+  if (!_defaultAdapter) {
+    throw new Error('No AI adapter registered.');
+  }
+  if (!_defaultAdapter.fixHoloScript) {
+    throw new Error(`AI adapter "${_defaultAdapter.name}" does not support fixHoloScript`);
+  }
+  return _defaultAdapter.fixHoloScript(holoScript, errors);
+}

package/src/ai/AICopilot.ts

@@ -0,0 +1,331 @@
+/**
+ * AICopilot.ts
+ *
+ * Editor-aware AI assistant that bridges the existing AIAdapter/HoloScriptGenerator
+ * infrastructure with the runtime and editor for real-time AI assistance.
+ *
+ * @module ai
+ */
+
+import { AIAdapter, GenerateOptions, GenerateResult } from './AIAdapter';
+import { HoloScriptGenerator, GeneratedCode } from './HoloScriptGenerator';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface CopilotContext {
+  /** Currently selected entity type/id */
+  selectedEntity?: { id: string; type: string; properties?: Record<string, unknown> };
+  /** Current scene node types */
+  sceneNodeTypes?: string[];
+  /** Active state keys */
+  stateKeys?: string[];
+  /** Recent user actions */
+  recentActions?: string[];
+}
+
+export interface CopilotSuggestion {
+  type: 'modify' | 'create' | 'explain' | 'fix';
+  description: string;
+  holoScript?: string;
+  confidence: number;
+}
+
+export interface CopilotResponse {
+  text: string;
+  suggestions: CopilotSuggestion[];
+  generatedCode?: GeneratedCode;
+  error?: string;
+}
+
+export interface CopilotMessage {
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp: number;
+}
+
+// =============================================================================
+// AI COPILOT
+// =============================================================================
+
+export class AICopilot {
+  private adapter: AIAdapter | null = null;
+  private generator: HoloScriptGenerator;
+  private history: CopilotMessage[] = [];
+  private context: CopilotContext = {};
+
+  constructor(adapter?: AIAdapter) {
+    this.generator = new HoloScriptGenerator();
+    if (adapter) {
+      this.setAdapter(adapter);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Adapter Management
+  // ---------------------------------------------------------------------------
+
+  setAdapter(adapter: AIAdapter): void {
+    this.adapter = adapter;
+    this.generator.createSession(adapter);
+  }
+
+  getAdapter(): AIAdapter | null {
+    return this.adapter;
+  }
+
+  isReady(): boolean {
+    return this.adapter !== null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Context Management
+  // ---------------------------------------------------------------------------
+
+  updateContext(context: Partial<CopilotContext>): void {
+    this.context = { ...this.context, ...context };
+  }
+
+  getContext(): CopilotContext {
+    return { ...this.context };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Core Operations
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Generate HoloScript from a natural language prompt.
+   * Uses the full HoloScriptGenerator pipeline (generate → validate → auto-fix).
+   */
+  async generateFromPrompt(
+    prompt: string,
+    options?: Partial<GenerateOptions>
+  ): Promise<CopilotResponse> {
+    const adapter = this.adapter;
+    if (!adapter) {
+      return {
+        text: 'No AI adapter configured. Please set an adapter first.',
+        suggestions: [],
+        error: 'NO_ADAPTER',
+      };
+    }
+    if (!adapter.generateHoloScript) {
+      return {
+        text: 'Adapter does not support generateHoloScript.',
+        suggestions: [],
+        error: 'UNSUPPORTED',
+      };
+    }
+
+    this.addMessage('user', prompt);
+
+    try {
+      const result = await adapter.generateHoloScript(prompt, {
+        targetPlatform: 'vr',
+        includePhysics: true,
+        ...options,
+      });
+
+      const response: CopilotResponse = {
+        text: `Generated HoloScript with ${result.objectCount || 'unknown'} objects (confidence: ${((result.confidence || 0) * 100).toFixed(0)}%).`,
+        suggestions: [
+          {
+            type: 'create',
+            description: `Create scene from: "${prompt}"`,
+            holoScript: result.holoScript,
+            confidence: result.confidence || 0,
+          },
+        ],
+      };
+
+      if (result.warnings?.length) {
+        response.text += ` Warnings: ${result.warnings.join(', ')}`;
+      }
+
+      this.addMessage('assistant', response.text);
+      return response;
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      this.addMessage('assistant', `Error: ${errorMsg}`);
+      return {
+        text: `Generation failed: ${errorMsg}`,
+        suggestions: [],
+        error: errorMsg,
+      };
+    }
+  }
+
+  /**
+   * Suggest modifications for the currently selected entity.
+   */
+  async suggestFromSelection(): Promise<CopilotResponse> {
+    const adapter = this.adapter;
+    if (!adapter) {
+      return { text: 'No adapter configured.', suggestions: [], error: 'NO_ADAPTER' };
+    }
+    if (!adapter.generateHoloScript) {
+      return {
+        text: 'Adapter does not support generateHoloScript.',
+        suggestions: [],
+        error: 'UNSUPPORTED',
+      };
+    }
+
+    const entity = this.context.selectedEntity;
+    if (!entity) {
+      return {
+        text: 'No entity selected. Select an entity in the editor first.',
+        suggestions: [],
+      };
+    }
+
+    const prompt = `Suggest improvements for a ${entity.type} entity with properties: ${JSON.stringify(entity.properties || {})}`;
+
+    try {
+      const result = await adapter.generateHoloScript(prompt, {
+        style: 'modern',
+        complexity: 'medium',
+      });
+
+      return {
+        text: `Suggestions for ${entity.type} (${entity.id}):`,
+        suggestions: [
+          {
+            type: 'modify',
+            description: `Enhance ${entity.type} with AI suggestions`,
+            holoScript: result.holoScript,
+            confidence: result.confidence || 0,
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        text: `Suggestion failed: ${error instanceof Error ? error.message : String(error)}`,
+        suggestions: [],
+        error: String(error),
+      };
+    }
+  }
+
+  /**
+   * Explain the current scene in natural language.
+   */
+  async explainScene(sceneCode: string): Promise<CopilotResponse> {
+    const adapter = this.adapter;
+    if (!adapter) {
+      return { text: 'No adapter configured.', suggestions: [], error: 'NO_ADAPTER' };
+    }
+    if (!adapter.explainHoloScript) {
+      return {
+        text: 'Adapter does not support explainHoloScript.',
+        suggestions: [],
+        error: 'UNSUPPORTED',
+      };
+    }
+
+    try {
+      const result = await adapter.explainHoloScript(sceneCode);
+      return {
+        text: result.explanation,
+        suggestions: [],
+      };
+    } catch (error) {
+      return {
+        text: `Explanation failed: ${error instanceof Error ? error.message : String(error)}`,
+        suggestions: [],
+        error: String(error),
+      };
+    }
+  }
+
+  /**
+   * Auto-fix runtime errors using the AI adapter.
+   */
+  async autoFix(code: string, errors: string[]): Promise<CopilotResponse> {
+    const adapter = this.adapter;
+    if (!adapter) {
+      return { text: 'No adapter configured.', suggestions: [], error: 'NO_ADAPTER' };
+    }
+    if (!adapter.fixHoloScript) {
+      return {
+        text: 'Adapter does not support fixHoloScript.',
+        suggestions: [],
+        error: 'UNSUPPORTED',
+      };
+    }
+
+    try {
+      const result = await adapter.fixHoloScript(code, errors);
+      return {
+        text: `Fixed ${result.fixes.length} issue(s).`,
+        suggestions: result.fixes.map((fix) => ({
+          type: 'fix' as const,
+          description: `Line ${fix.line}: ${fix.issue} → ${fix.fix}`,
+          holoScript: result.holoScript,
+          confidence: 0.8,
+        })),
+      };
+    } catch (error) {
+      return {
+        text: `Auto-fix failed: ${error instanceof Error ? error.message : String(error)}`,
+        suggestions: [],
+        error: String(error),
+      };
+    }
+  }
+
+  /**
+   * Chat with the AI about HoloScript code (multi-turn conversation).
+   */
+  async chat(message: string): Promise<CopilotResponse> {
+    const adapter = this.adapter;
+    if (!adapter) {
+      return { text: 'No adapter configured.', suggestions: [], error: 'NO_ADAPTER' };
+    }
+    if (!adapter.chat) {
+      return { text: 'Adapter does not support chat.', suggestions: [], error: 'UNSUPPORTED' };
+    }
+
+    this.addMessage('user', message);
+
+    try {
+      const chatHistory = this.history.map((m) => ({
+        role: m.role,
+        content: m.content,
+      }));
+
+      const response = await adapter.chat(message, undefined, chatHistory);
+      this.addMessage('assistant', response);
+
+      return {
+        text: response,
+        suggestions: [],
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      return {
+        text: `Chat failed: ${errorMsg}`,
+        suggestions: [],
+        error: errorMsg,
+      };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // History Management
+  // ---------------------------------------------------------------------------
+
+  getHistory(): CopilotMessage[] {
+    return [...this.history];
+  }
+
+  clearHistory(): void {
+    this.history = [];
+  }
+
+  private addMessage(role: 'user' | 'assistant', content: string): void {
+    this.history.push({ role, content, timestamp: Date.now() });
+  }
+}