@koi-language/koi 1.0.5 → 1.1.0

package/src/compiler/build-optimizer.js

@@ -1,11 +1,8 @@
 /**
  * Build-Time Optimizer
  *
- * Pre-computes expensive operations during compilation to avoid runtime overhead:
- * - Embeddings for agent affordances (with persistent caching)
- * - Static agent metadata
- * - Any other cacheable data
- *
+ * Pre-computes handler descriptions during compilation to avoid runtime overhead.
+ * Uses a SINGLE batched LLM call to summarize all handlers at once.
  * Uses SHA-256 content hashing to detect changes and avoid redundant API calls.
  */
 
@@ -16,8 +13,6 @@ export class BuildTimeOptimizer {
   constructor(config = {}) {
     this.enableCache = config.cache !== false;
     this.verbose = config.verbose || false;
-    this.llmProvider = null;  // For embeddings
-    this.chatProvider = null;  // For code introspection
     this.cacheManager = new CacheManager({
       verbose: config.verbose || false
     });
@@ -25,9 +20,6 @@ export class BuildTimeOptimizer {
 
   /**
    * Extract and pre-compute affordances from AST (with cache)
-   * @param ast - Abstract syntax tree
-   * @param sourceContent - Original source code content (for cache hashing)
-   * @param sourcePath - Path to source file (for cache tracking)
    */
   async optimizeAST(ast, sourceContent = '', sourcePath = 'unknown') {
     if (!this.enableCache) {
@@ -35,348 +27,292 @@ export class BuildTimeOptimizer {
       return null;
     }
 
-    console.log('🔄 [BuildOptimizer] Checking cache...');
+    process.stdout.write('\r\x1b[K🔄 Checking cache...');
 
-    // Check if we have cached data for this exact source content
     const cached = this.cacheManager.get(sourceContent, sourcePath);
     if (cached) {
-      const totalAffordances = (cached.metadata.totalAffordances || 0) + (cached.metadata.totalSkillAffordances || 0);
-      console.log(`✅ [BuildOptimizer] Using cached embeddings (${totalAffordances} affordances)`);
-      console.log(`   Last generated: ${new Date(cached.metadata.generatedAt).toLocaleString()}`);
-      console.log(`   💰 Saved API calls!`);
+      process.stdout.write('\r\x1b[K');
       return cached;
     }
 
-    // Cache miss - generate embeddings
-    console.log('🔄 [BuildOptimizer] Cache miss, pre-computing embeddings...');
+    process.stdout.write('\r\x1b[K🔄 Generating handler descriptions...');
+
+    const result = await this._generateAllDescriptions(ast);
+
+    process.stdout.write('\r\x1b[K');
+
+    this.cacheManager.set(sourceContent, sourcePath, result);
+    return result;
+  }
+
+  /**
+   * Extract and pre-compute affordances from AST (without cache)
+   */
+  async optimizeASTWithoutCache(ast) {
+    const result = await this._generateAllDescriptions(ast);
+    process.stdout.write('\r\x1b[K');
+    return result;
+  }
 
+  /**
+   * Core: collect all handlers, make ONE batched LLM call, distribute results
+   */
+  async _generateAllDescriptions(ast) {
     const affordances = {};
     const skillAffordances = {};
-    let totalEmbeddings = 0;
-    let totalSkillEmbeddings = 0;
 
-    // Find all declarations in AST
+    // 1. Collect all handlers that need descriptions
+    const handlerEntries = []; // { agentName, eventName, content, hasPlaybook }
+
     for (const decl of ast.declarations) {
       if (decl.type === 'AgentDecl') {
-        const agentAffordances = await this.extractAgentAffordances(decl);
-
-        if (agentAffordances && Object.keys(agentAffordances).length > 0) {
-          affordances[decl.name.name] = agentAffordances;
-          totalEmbeddings += Object.keys(agentAffordances).length;
+        const agentName = decl.name.name;
+        const eventHandlers = decl.body.filter(b => b.type === 'EventHandler');
+
+        for (const handler of eventHandlers) {
+          const eventName = handler.event.name;
+          const playbook = this.findPlaybookForHandler(handler);
+
+          if (playbook) {
+            const clean = playbook.replace(/\$\{[^}]+\}/g, '...');
+            handlerEntries.push({
+              agentName, eventName, content: clean, hasPlaybook: true
+            });
+          } else {
+            const code = this._serializeHandlerCode(handler);
+            handlerEntries.push({
+              agentName, eventName, content: code || eventName, hasPlaybook: false
+            });
+          }
         }
       } else if (decl.type === 'SkillDecl') {
-        const skillData = await this.extractSkillAffordance(decl);
-
+        const skillData = this.extractSkillAffordance(decl);
         if (skillData) {
           skillAffordances[decl.name.name] = skillData;
-          totalSkillEmbeddings++;
         }
       }
     }
 
-    console.log(`✅ [BuildOptimizer] Pre-computed ${totalEmbeddings + totalSkillEmbeddings} embeddings (${totalEmbeddings} agents, ${totalSkillEmbeddings} skills)`);
-
-    const result = {
-      affordances,
-      skillAffordances,
-      metadata: {
-        generatedAt: Date.now(),
-        totalAgents: Object.keys(affordances).length,
-        totalAffordances: totalEmbeddings,
-        totalSkills: Object.keys(skillAffordances).length,
-        totalSkillAffordances: totalSkillEmbeddings
-      }
-    };
+    // 2. If no handlers, return empty
+    if (handlerEntries.length === 0) {
+      return this._buildResult(affordances, skillAffordances);
+    }
 
-    // Store in cache
-    this.cacheManager.set(sourceContent, sourcePath, result);
+    // 3. Get descriptions via single batched LLM call
+    const descriptions = await this._batchSummarize(handlerEntries, ast);
 
-    return result;
-  }
+    // 4. Distribute descriptions into affordances map
+    for (let i = 0; i < handlerEntries.length; i++) {
+      const entry = handlerEntries[i];
+      const description = descriptions[i] || this.humanizeEventName(entry.eventName);
 
-  /**
-   * Extract and pre-compute affordances from AST (without cache)
-   * Generates embeddings but doesn't store them in persistent cache
-   * @param ast - Abstract syntax tree
-   */
-  async optimizeASTWithoutCache(ast) {
-    const affordances = {};
-    let totalEmbeddings = 0;
+      if (!affordances[entry.agentName]) {
+        affordances[entry.agentName] = {};
+      }
 
-    // Find all agent declarations in AST
-    for (const decl of ast.declarations) {
-      if (decl.type === 'AgentDecl') {
-        const agentAffordances = await this.extractAgentAffordances(decl);
+      affordances[entry.agentName][entry.eventName] = {
+        description,
+        confidence: entry.hasPlaybook ? 0.9 : 0.8,
+        hasPlaybook: entry.hasPlaybook
+      };
 
-        if (agentAffordances && Object.keys(agentAffordances).length > 0) {
-          affordances[decl.name.name] = agentAffordances;
-          totalEmbeddings += Object.keys(agentAffordances).length;
-        }
+      if (this.verbose) {
+        console.log(`    ✓ ${entry.agentName}.${entry.eventName}: "${description.substring(0, 50)}..."`);
       }
     }
 
-    console.log(`✅ [BuildOptimizer] Pre-computed ${totalEmbeddings} embeddings (no cache)`);
-
-    return {
-      affordances,
-      metadata: {
-        generatedAt: Date.now(),
-        totalAgents: Object.keys(affordances).length,
-        totalAffordances: totalEmbeddings
-      }
-    };
+    return this._buildResult(affordances, skillAffordances);
   }
 
   /**
-   * Extract affordances for a single agent
+   * Single batched LLM call to summarize all handlers at once
    */
-  async extractAgentAffordances(agentNode) {
-    const affordances = {};
+  async _batchSummarize(entries, ast) {
+    // Pick the first agent's LLM config, or fallback to openai/gpt-4o-mini
+    const firstAgentDecl = ast.declarations.find(d => d.type === 'AgentDecl');
+    const agentLLM = firstAgentDecl ? this.extractLLMConfig(firstAgentDecl) : null;
+    const provider = this.getOrCreateChatProvider(agentLLM);
 
-    // Find event handlers
-    const eventHandlers = agentNode.body.filter(b => b.type === 'EventHandler');
+    // Build batch prompt
+    const items = entries.map((e, i) => {
+      const type = e.hasPlaybook ? 'Playbook' : 'Code';
+      return `${i + 1}. Agent "${e.agentName}", handler "${e.eventName}" (${type}):\n${e.content}`;
+    }).join('\n\n');
 
-    if (eventHandlers.length === 0) {
-      return affordances;
-    }
+    const prompt = `Summarize each handler below in ONE short sentence (max 15 words each).
+Return one summary per line, numbered to match. Plain English only, no JSON.
 
-    if (this.verbose) {
-      console.log(`  [Agent:${agentNode.name.name}] Extracting ${eventHandlers.length} affordances...`);
-    }
+${items}`;
 
-    for (const handler of eventHandlers) {
-      const eventName = handler.event.name;
-
-      // Try to find playbook
-      const playbook = this.findPlaybookForHandler(handler);
-
-      let description;
-      let confidence;
-      let hasPlaybook = false;
-
-      if (playbook) {
-        // Extract description from playbook
-        description = this.inferIntentFromPlaybook(playbook, eventName);
-        confidence = 0.9;
-        hasPlaybook = true;
-      } else {
-        // No playbook - use code introspection
-        description = await this.introspectHandlerCode(handler, eventName);
-        confidence = 0.8; // High confidence since we analyzed the actual code
-        hasPlaybook = false;
-      }
+    try {
+      const response = await provider.simpleChat(prompt);
 
-      // Validate description
-      if (!description || description.trim() === '') {
-        console.warn(`⚠️  [BuildOptimizer] Empty description for ${agentNode.name.name}.${eventName}, skipping embedding`);
-        description = `Handler: ${eventName}`;
+      if (!response) {
+        return entries.map(e => this._fallbackDescription(e));
       }
 
-      // Generate embedding
-      const embedding = await this.generateEmbedding(description);
+      // Parse numbered lines: "1. description" or "1: description" or just lines
+      const lines = response.split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0);
+
+      const descriptions = new Array(entries.length);
+
+      for (const line of lines) {
+        // Try to match "N. description" or "N: description"
+        const match = line.match(/^(\d+)[.):]\s*(.+)/);
+        if (match) {
+          const idx = parseInt(match[1]) - 1;
+          const desc = match[2].trim();
+          if (idx >= 0 && idx < entries.length && desc.length > 3) {
+            // Reject JSON responses
+            if (!desc.startsWith('{') && !desc.startsWith('[')) {
+              descriptions[idx] = desc;
+            }
+          }
+        }
+      }
 
-      affordances[eventName] = {
-        description: description,
-        embedding: embedding,
-        confidence: confidence,
-        hasPlaybook: hasPlaybook
-      };
+      // Fill gaps with fallbacks
+      for (let i = 0; i < entries.length; i++) {
+        if (!descriptions[i]) {
+          descriptions[i] = this._fallbackDescription(entries[i]);
+        }
+      }
 
+      return descriptions;
+    } catch (error) {
       if (this.verbose) {
-        console.log(`    ✓ ${eventName}: "${description.substring(0, 50)}..."`);
+        console.warn(`[BuildOptimizer] Batch summarization failed: ${error.message}`);
       }
+      return entries.map(e => this._fallbackDescription(e));
     }
-
-    return affordances;
   }
 
   /**
-   * Find playbook for an event handler
+   * Fallback description when LLM fails
    */
-  findPlaybookForHandler(handler) {
-    // Check if handler has a playbook statement
-    for (const stmt of handler.body) {
-      if (stmt.type === 'PlaybookStatement') {
-        return stmt.content.value;
-      }
+  _fallbackDescription(entry) {
+    if (entry.hasPlaybook) {
+      const lines = entry.content
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0 && !l.startsWith('//') && !l.startsWith('Return'))
+        .slice(0, 2)
+        .join(' ');
+      return lines.length > 10 ? lines.substring(0, 100) : this.humanizeEventName(entry.eventName);
     }
-
-    return null;
+    return this.humanizeEventName(entry.eventName);
   }
 
   /**
-   * Infer intent from playbook text
+   * Serialize handler body to readable code summary
    */
-  inferIntentFromPlaybook(playbook, eventName) {
-    // Handle non-string playbooks
-    if (!playbook || typeof playbook !== 'string') {
-      return this.humanizeEventName(eventName);
+  _serializeHandlerCode(handler) {
+    const lines = [];
+    for (const stmt of handler.body) {
+      const code = this.serializeStatement(stmt);
+      if (code) lines.push(code);
     }
+    return lines.join('\n') || null;
+  }
 
-    // Remove template literals
-    const cleanText = playbook
-      .replace(/\$\{[^}]+\}/g, '')
-      .split('\n')
-      .map(line => line.trim())
-      .filter(line => line.length > 0 && !line.startsWith('//') && !line.startsWith('Return'))
-      .slice(0, 3) // Take first 3 lines
-      .join(' ');
-
-    if (cleanText.length > 10 && cleanText.length < 200) {
-      return cleanText;
+  _buildResult(affordances, skillAffordances) {
+    let totalAffordances = 0;
+    for (const agent of Object.values(affordances)) {
+      totalAffordances += Object.keys(agent).length;
     }
-
-    // Fallback
-    return this.humanizeEventName(eventName);
+    return {
+      affordances,
+      skillAffordances,
+      metadata: {
+        generatedAt: Date.now(),
+        totalAgents: Object.keys(affordances).length,
+        totalAffordances,
+        totalSkills: Object.keys(skillAffordances).length,
+        totalSkillAffordances: Object.keys(skillAffordances).length
+      }
+    };
   }
 
-  /**
-   * Introspect handler code using LLM to understand what it does
-   * @param handler - Event handler AST node
-   * @param eventName - Name of the event
-   * @returns Description of what the handler does
-   */
-  async introspectHandlerCode(handler, eventName) {
-    // Serialize the handler body to source code
-    const codeLines = [];
+  // --- Helper methods ---
 
+  findPlaybookForHandler(handler) {
     for (const stmt of handler.body) {
-      const code = this.serializeStatement(stmt);
-      if (code) {
-        codeLines.push(code);
+      if (stmt.type === 'PlaybookStatement') {
+        return stmt.content.value;
       }
     }
+    return null;
+  }
 
-    const sourceCode = codeLines.join('\n');
+  extractLLMConfig(agentNode) {
+    const llmConfig = agentNode.body.find(b => b.type === 'LLMConfig');
+    if (!llmConfig || !llmConfig.config || !llmConfig.config.properties) return null;
 
-    // If no code, fallback to event name
-    if (!sourceCode || sourceCode.trim().length === 0) {
-      return this.humanizeEventName(eventName);
+    const props = {};
+    for (const prop of llmConfig.config.properties) {
+      const key = prop.key?.name || prop.key;
+      const val = prop.value?.value;
+      if (key && val !== undefined) props[key] = val;
     }
+    return props.provider && props.model ? props : null;
+  }
 
-    // Use LLM to analyze the code
-    if (!this.chatProvider) {
-      this.initChatProvider();
-    }
-
-    const introspectionPrompt = `Analyze this event handler code and provide a concise description (1-2 sentences) of what it does.
-
-Event name: ${eventName}
-
-Code:
-\`\`\`javascript
-${sourceCode}
-\`\`\`
-
-Focus on:
-- What operations it performs
-- What data it processes or returns
-- Its main purpose or capability
+  extractSkillAffordance(skillNode) {
+    const affordanceText = skillNode.affordance?.value || skillNode.affordance || '';
 
-Return ONLY the description text, no markdown, no explanations, no prefix like "This handler...". Just a direct description.`;
+    if (!affordanceText || affordanceText.trim().length === 0) {
+      const description = this.humanizeEventName(skillNode.name.name);
+      return { description, confidence: 0.5 };
+    }
 
-    try {
-      const response = await this.chatProvider.executeOpenAI(introspectionPrompt, false);
+    let cleanDescription = affordanceText
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line.length > 0)
+      .join(' ')
+      .trim();
 
-      // Clean up the response
-      const description = response
-        .replace(/^(This handler|This event handler|This function|The handler|The function)\s*/i, '')
-        .replace(/^(handles?|processes?|performs?)\s*/i, '')
-        .trim();
+    if (!cleanDescription || cleanDescription.length === 0) {
+      cleanDescription = this.humanizeEventName(skillNode.name.name);
+    }
 
-      if (description && description.length > 10) {
-        return description;
-      }
-    } catch (error) {
-      console.warn(`[BuildOptimizer] Code introspection failed for ${eventName}:`, error.message);
+    if (this.verbose) {
+      console.log(`    ✓ Skill ${skillNode.name.name}: "${cleanDescription.substring(0, 50)}..."`);
     }
 
-    // Fallback to humanized event name
-    return this.humanizeEventName(eventName);
+    return { description: cleanDescription, confidence: 0.9 };
   }
 
-  /**
-   * Serialize an AST statement to source code (simplified)
-   */
   serializeStatement(stmt) {
     if (!stmt) return '';
 
     switch (stmt.type) {
       case 'ConstDeclaration':
         return `const ${stmt.name.name} = ...`;
-
       case 'ReturnStatement':
         if (stmt.value && stmt.value.type === 'ObjectLiteral') {
-          // Extract object keys
           const keys = stmt.value.properties?.map(p => p.key?.name || p.key).join(', ') || '';
           return `return { ${keys} }`;
         }
         return 'return ...';
-
-      case 'SendStatement':
+      case 'SendStatement': {
         const role = stmt.role?.name || 'Role';
         const event = stmt.event?.name || 'event';
         return `send to ${role}.${event}()`;
-
+      }
       case 'ExpressionStatement':
         if (stmt.expression?.type === 'CallExpression') {
           const callee = stmt.expression.callee?.name || stmt.expression.callee?.property?.name || 'function';
           return `${callee}(...)`;
         }
         return '...';
-
       default:
         return `// ${stmt.type}`;
     }
   }
 
-  /**
-   * Extract affordance for a skill
-   */
-  async extractSkillAffordance(skillNode) {
-    // Skills have an explicit affordance field
-    const affordanceText = skillNode.affordance?.value || skillNode.affordance || '';
-
-    if (!affordanceText || affordanceText.trim().length === 0) {
-      // No affordance defined - use skill name as fallback
-      const description = this.humanizeEventName(skillNode.name.name);
-      return {
-        description,
-        embedding: await this.generateEmbedding(description),
-        confidence: 0.5
-      };
-    }
-
-    // Clean up affordance text (remove extra whitespace/newlines)
-    let cleanDescription = affordanceText
-      .split('\n')
-      .map(line => line.trim())
-      .filter(line => line.length > 0)
-      .join(' ')
-      .trim();
-
-    // Validate description is not empty
-    if (!cleanDescription || cleanDescription.length === 0) {
-      cleanDescription = this.humanizeEventName(skillNode.name.name);
-    }
-
-    // Generate embedding for the affordance
-    const embedding = await this.generateEmbedding(cleanDescription);
-
-    if (this.verbose) {
-      console.log(`    ✓ Skill ${skillNode.name.name}: "${cleanDescription.substring(0, 50)}..."`);
-    }
-
-    return {
-      description: cleanDescription,
-      embedding: embedding,
-      confidence: 0.9
-    };
-  }
-
-  /**
-   * Humanize event name
-   */
   humanizeEventName(eventName) {
     return eventName
       .replace(/([A-Z])/g, ' $1')
@@ -385,48 +321,29 @@ Return ONLY the description text, no markdown, no explanations, no prefix like "
       .trim();
   }
 
-  /**
-   * Initialize chat LLM provider for code introspection
-   */
-  initChatProvider() {
-    this.chatProvider = new LLMProvider({
-      provider: 'openai',
-      model: 'gpt-4o-mini',  // Fast and cheap model for code analysis
-      temperature: 0.1,
-      maxTokens: 150
-    });
-  }
+  getOrCreateChatProvider(agentLLM = null) {
+    const provider = agentLLM?.provider || 'openai';
+    const model = agentLLM?.model || 'gpt-4o-mini';
+    const key = `${provider}:${model}`;
 
-  /**
-   * Generate embedding for text
-   */
-  async generateEmbedding(text) {
-    if (!this.llmProvider) {
-      this.llmProvider = new LLMProvider({
-        provider: 'openai',
-        model: 'text-embedding-3-small'
-      });
-    }
+    if (!this._chatProviders) this._chatProviders = new Map();
 
-    try {
-      return await this.llmProvider.getEmbedding(text);
-    } catch (error) {
-      console.warn(`[BuildOptimizer] Failed to generate embedding: ${error.message}`);
-      return null;
+    if (!this._chatProviders.has(key)) {
+      this._chatProviders.set(key, new LLMProvider({
+        provider,
+        model,
+        temperature: 0.1,
+        maxTokens: 300 // Enough for batch response
+      }));
     }
+
+    return this._chatProviders.get(key);
   }
 
-  /**
-   * Generate JavaScript code for cached data
-   */
   generateCacheCode(cacheData) {
-    if (!cacheData) {
-      return '';
-    }
+    if (!cacheData) return '';
 
-    const totalAffordances = (cacheData.metadata.totalAffordances || 0) + (cacheData.metadata.totalSkillAffordances || 0);
-
-    const code = `
+    return `
 // ============================================================
 // Pre-computed Affordances (Build-time Cache)
 // Generated at: ${new Date(cacheData.metadata.generatedAt).toISOString()}
@@ -441,7 +358,5 @@ const CACHED_AFFORDANCES = ${JSON.stringify(cacheData.affordances || {}, null, 2
 const CACHED_SKILL_AFFORDANCES = ${JSON.stringify(cacheData.skillAffordances || {}, null, 2)};
 
 `;
-
-    return code;
   }
 }

package/src/compiler/cache-manager.js

@@ -17,7 +17,7 @@ const __dirname = path.dirname(__filename);
 export class CacheManager {
   constructor(config = {}) {
     // Cache directory relative to project root
-    this.cacheDir = config.cacheDir || path.join(process.cwd(), '.koi-cache');
+    this.cacheDir = config.cacheDir || path.join(process.cwd(), '.koi', 'cache');
     this.verbose = config.verbose || false;
 
     // Ensure cache directory exists