@holoscript/framework 6.0.3

package/src/learning/MemoryConsolidator.ts

@@ -0,0 +1,102 @@
+const logger = { info: console.info, error: console.error };
+
+export interface EpisodicMemory {
+  id: string;
+  timestamp: number;
+  action: string;
+  outcome: string;
+  entitiesInvolved: string[];
+  semanticVector?: number[]; // Mock embedding
+}
+
+export interface SemanticFact {
+  id: string;
+  fact: string;
+  confidence: number;
+  sourceEpisodes: string[];
+}
+
+/**
+ * MemoryConsolidator
+ *
+ * Compresses raw episodic events into structured semantic facts
+ * via idle background cycles, mirroring human sleep consolidation.
+ */
+export class MemoryConsolidator {
+  /**
+   * Identifies conceptually similar episodic memories based on shared entities and actions.
+   */
+  private static clusterEpisodes(episodes: EpisodicMemory[]): EpisodicMemory[][] {
+    const clusters: Record<string, EpisodicMemory[]> = {};
+
+    // Basic heuristic: Cluster by primary action and first entity
+    for (const ep of episodes) {
+      const key = `${ep.action}_${ep.entitiesInvolved[0] || 'generic'}`;
+      if (!clusters[key]) clusters[key] = [];
+      clusters[key].push(ep);
+    }
+
+    return Object.values(clusters);
+  }
+
+  /**
+   * Mocks an LLM-based summarization pass converting a cluster of raw events
+   * into a single concrete semantic truth.
+   */
+  private static summarizeCluster(cluster: EpisodicMemory[]): SemanticFact | null {
+    if (cluster.length < 3) return null; // Only consolidate recurring patterns
+
+    const sample = cluster[0];
+    const successCount = cluster.filter((ep) => ep.outcome.includes('success')).length;
+    const successRate = successCount / cluster.length;
+
+    let rule = '';
+    if (successRate > 0.7) {
+      rule = `${sample.action} applied to ${sample.entitiesInvolved[0]} is generally effective.`;
+    } else {
+      rule = `${sample.action} applied to ${sample.entitiesInvolved[0]} has high failure risk.`;
+    }
+
+    return {
+      id: `fact_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+      fact: rule,
+      confidence: successRate,
+      sourceEpisodes: cluster.map((c) => c.id),
+    };
+  }
+
+  /**
+   * Executes the background consolidation pass.
+   * Takes raw episodes, clusters them, extracts truths, and returns the facts
+   * while reporting which raw episodes can be safely garbage collected.
+   */
+  static compressEpisodes(rawEpisodes: EpisodicMemory[]): {
+    newFacts: SemanticFact[];
+    prunedEpisodes: string[];
+  } {
+    if (rawEpisodes.length < 5) return { newFacts: [], prunedEpisodes: [] };
+
+    logger.info(
+      `[Consolidation] Running idle memory compression on ${rawEpisodes.length} episodes.`
+    );
+
+    const clusters = this.clusterEpisodes(rawEpisodes);
+    const newFacts: SemanticFact[] = [];
+    const prunedEpisodes: string[] = [];
+
+    for (const cluster of clusters) {
+      const fact = this.summarizeCluster(cluster);
+      if (fact) {
+        newFacts.push(fact);
+        // Mark these source episodes for pruning since we extracted the semantic truth
+        prunedEpisodes.push(...fact.sourceEpisodes);
+      }
+    }
+
+    logger.info(
+      `[Consolidation] Distilled ${prunedEpisodes.length} raw episodes into ${newFacts.length} semantic facts.`
+    );
+
+    return { newFacts, prunedEpisodes };
+  }
+}

package/src/learning/MemoryScorer.ts

@@ -0,0 +1,69 @@
+/**
+ * MemoryScorer
+ *
+ * Generates an 'importance' dimensional scalar for Episodic memories.
+ * Allows the aggregation engine to aggressively prune trivial loops (like 'Idle')
+ * and permanently archive high-value bounds (like 'Combat' or 'Crafting').
+ */
+
+export interface EpisodicEvent {
+  agentId: string;
+  timestamp: number;
+  action: string;
+  context: Record<string, any>;
+  outcome: string;
+}
+
+export class MemoryScorer {
+  /**
+   * Scores an event from -100 (Absolute Noise) to 100 (Critical Experience).
+   */
+  static computeImportance(event: EpisodicEvent): number {
+    let score = 0;
+
+    // 1. Action Density Weighting
+    const action = event.action.toLowerCase();
+    if (action.includes('idle') || action.includes('wait') || action.includes('sleep')) {
+      score -= 50;
+    } else if (action.includes('move') || action.includes('look') || action.includes('walk')) {
+      score -= 10;
+    } else if (action.includes('craft') || action.includes('build') || action.includes('analyze')) {
+      score += 30;
+    } else if (
+      action.includes('combat') ||
+      action.includes('attack') ||
+      action.includes('defense') ||
+      action.includes('damage')
+    ) {
+      score += 50;
+    }
+
+    // 2. Context Entropy (More complex context = higher density value)
+    const contextKeys = Object.keys(event.context || {}).length;
+    score += Math.min(20, contextKeys * 2);
+
+    // 3. Outcome Variance (Is the outcome signifying a concrete change?)
+    const outcome = event.outcome.toLowerCase();
+    if (outcome.includes('failed') || outcome.includes('error')) {
+      score += 25; // Agent failures are important for negative reinforcement
+    } else if (
+      outcome.includes('success') ||
+      outcome.includes('crafted') ||
+      outcome.includes('killed')
+    ) {
+      score += 25; // Major achievements are important for positive reinforcement
+    } else if (outcome.includes('nothing') || outcome.includes('none')) {
+      score -= 20; // Zero variance
+    }
+
+    // Clamp between -100 and 100
+    return Math.max(-100, Math.min(100, score));
+  }
+
+  /**
+   * Filters arrays natively discarding negative arrays
+   */
+  static cullLowImportance(events: EpisodicEvent[], threshold: number = 0): EpisodicEvent[] {
+    return events.filter((e) => this.computeImportance(e) >= threshold);
+  }
+}

package/src/learning/ProceduralCompiler.ts

@@ -0,0 +1,45 @@
+export interface ProceduralSkill { id: string; name: string; description?: string; code?: string; }
+
+/**
+ * ProceduralCompiler
+ *
+ * Takes JSON-based AI logic trees extracted from temporal LLM generation natively
+ * and compiles them strictly down into raw executable `.holo` syntax bounds.
+ */
+export class ProceduralCompiler {
+  /**
+   * Translates an Abstract Skill representation into native text executing within the VM.
+   */
+  static compile(skill: ProceduralSkill): string {
+    let compiled = `// Auto-generated skill: ${skill.name}\n`;
+    compiled += `// Desc: ${(skill as unknown as { description?: string }).description || 'N/A'}\n\n`;
+
+    compiled += `agent ${skill.id.replace(/-/g, '_')} {\n`;
+
+    // Generate behavior node
+    compiled += `  behavior execute() {\n`;
+
+    const codeBlock = (skill as unknown as { code?: string }).code || '';
+
+    // MVP: The LLM outputs pseudo-code or raw JS/HoloScript lines directly in string
+    // The procedural compiler validates and formats the raw string cleanly
+    const parsedLines = codeBlock.split('\n');
+
+    for (let line of parsedLines) {
+      line = line.trim();
+      if (!line) continue;
+
+      // Map some logical conversions if needed, here we just enforce safety wrappers
+      if (line.includes('move(') || line.includes('attack(') || line.includes('craft(')) {
+        compiled += `    ensure_safety() {\n      ${line}\n    }\n`;
+      } else {
+        compiled += `    ${line}\n`;
+      }
+    }
+
+    compiled += `  }\n`;
+    compiled += `}\n`;
+
+    return compiled;
+  }
+}

package/src/learning/SemanticClusterer.ts

@@ -0,0 +1,66 @@
+import { EpisodicEvent } from './MemoryScorer';
+
+/**
+ * SemanticClusterer
+ *
+ * Compresses raw temporal Episodic buffers into distilled arrays.
+ * Native distillation drops repeating trivial structures mapping them into aggregated
+ * density nodes explicitly reducing database storage loads across vector boundaries.
+ */
+export class SemanticClusterer {
+  /**
+   * Actively squash sequentially repeating abstract patterns mapping out semantic arrays.
+   */
+  static distill(events: EpisodicEvent[]): EpisodicEvent[] {
+    if (events.length === 0) return [];
+
+    const distilled: EpisodicEvent[] = [];
+    let currentSequence: EpisodicEvent = { ...events[0] };
+    let repetitonCount = 1;
+
+    for (let i = 1; i < events.length; i++) {
+      const ev = events[i];
+
+      // If the Action and Target align, we squash them and increment the density metrics
+      if (this.isSimilar(currentSequence, ev)) {
+        repetitonCount++;
+        currentSequence.outcome = `Repeated action successfully (${repetitonCount} times)`;
+
+        // Track total time span passed over the squash boundary
+        if (!currentSequence.context.timeSpanStarted) {
+          currentSequence.context.timeSpanStarted = currentSequence.timestamp;
+        }
+        currentSequence.context.timeSpanEnded = ev.timestamp;
+      } else {
+        // Similarity broken. Push distilled sequence array and begin anew.
+        if (repetitonCount > 1) {
+          currentSequence.action = `${currentSequence.action}_Aggregated`;
+        }
+        distilled.push({ ...currentSequence });
+
+        currentSequence = { ...ev };
+        repetitonCount = 1;
+      }
+    }
+
+    // Push final buffer
+    if (repetitonCount > 1) {
+      currentSequence.action = `${currentSequence.action}_Aggregated`;
+    }
+    distilled.push(currentSequence);
+
+    return distilled;
+  }
+
+  /**
+   * Determines heuristic thresholds to squash logic natively offline without LLM.
+   */
+  private static isSimilar(a: EpisodicEvent, b: EpisodicEvent): boolean {
+    if (a.action !== b.action) return false;
+
+    const aTarget = a.context?.target || a.context?.location;
+    const bTarget = b.context?.target || b.context?.location;
+
+    return aTarget === bTarget;
+  }
+}

package/src/learning/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Learning module barrel
+ * Re-exports all learning functionality from @holoscript/framework
+ */
+export * from './MemoryConsolidator';
+export * from './MemoryScorer';
+export * from './ProceduralCompiler';
+export * from './SemanticClusterer';

package/src/llm/llm-adapter.ts

@@ -0,0 +1,159 @@
+/**
+ * Provider-Agnostic LLM Adapter
+ *
+ * Thin wrapper that dispatches to Anthropic, OpenAI, xAI, or OpenRouter.
+ * Each agent can use a different provider/model.
+ */
+
+import type { ModelConfig } from '../types';
+
+export interface LLMMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface LLMResponse {
+  content: string;
+  model: string;
+  provider: string;
+  tokensUsed?: number;
+}
+
+export async function callLLM(
+  config: ModelConfig,
+  messages: LLMMessage[],
+  options: { maxTokens?: number; temperature?: number } = {}
+): Promise<LLMResponse> {
+  const maxTokens = options.maxTokens ?? config.maxTokens ?? 1024;
+  const temperature = options.temperature ?? config.temperature ?? 0.7;
+
+  switch (config.provider) {
+    case 'anthropic':
+      return callAnthropic(config, messages, maxTokens, temperature);
+    case 'openai':
+    case 'xai':
+      return callOpenAICompatible(config, messages, maxTokens, temperature);
+    case 'openrouter':
+      return callOpenRouter(config, messages, maxTokens, temperature);
+    default:
+      throw new Error(`Unknown LLM provider: ${config.provider}`);
+  }
+}
+
+async function callAnthropic(
+  config: ModelConfig,
+  messages: LLMMessage[],
+  maxTokens: number,
+  temperature: number
+): Promise<LLMResponse> {
+  const apiKey = config.apiKey || process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) throw new Error('ANTHROPIC_API_KEY required');
+
+  const system = messages.filter(m => m.role === 'system').map(m => m.content).join('\n');
+  const userMessages = messages.filter(m => m.role !== 'system').map(m => ({
+    role: m.role as 'user' | 'assistant',
+    content: m.content,
+  }));
+
+  const res = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: config.model,
+      max_tokens: maxTokens,
+      temperature,
+      system: system || undefined,
+      messages: userMessages,
+    }),
+    signal: AbortSignal.timeout(60_000),
+  });
+
+  if (!res.ok) throw new Error(`Anthropic API error: ${res.status}`);
+  const data = await res.json() as { content: Array<{ text: string }>; usage?: { output_tokens: number } };
+
+  return {
+    content: data.content?.[0]?.text || '',
+    model: config.model,
+    provider: 'anthropic',
+    tokensUsed: data.usage?.output_tokens,
+  };
+}
+
+async function callOpenAICompatible(
+  config: ModelConfig,
+  messages: LLMMessage[],
+  maxTokens: number,
+  temperature: number
+): Promise<LLMResponse> {
+  const isXAI = config.provider === 'xai';
+  const apiKey = config.apiKey || (isXAI ? process.env.XAI_API_KEY : process.env.OPENAI_API_KEY);
+  if (!apiKey) throw new Error(`${config.provider.toUpperCase()}_API_KEY required`);
+
+  const baseUrl = isXAI ? 'https://api.x.ai/v1' : 'https://api.openai.com/v1';
+
+  const res = await fetch(`${baseUrl}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: config.model,
+      max_tokens: maxTokens,
+      temperature,
+      messages: messages.map(m => ({ role: m.role, content: m.content })),
+    }),
+    signal: AbortSignal.timeout(60_000),
+  });
+
+  if (!res.ok) throw new Error(`${config.provider} API error: ${res.status}`);
+  const data = await res.json() as { choices: Array<{ message: { content: string } }>; usage?: { completion_tokens: number } };
+
+  return {
+    content: data.choices?.[0]?.message?.content || '',
+    model: config.model,
+    provider: config.provider,
+    tokensUsed: data.usage?.completion_tokens,
+  };
+}
+
+async function callOpenRouter(
+  config: ModelConfig,
+  messages: LLMMessage[],
+  maxTokens: number,
+  temperature: number
+): Promise<LLMResponse> {
+  const apiKey = config.apiKey || process.env.OPENROUTER_API_KEY;
+  if (!apiKey) throw new Error('OPENROUTER_API_KEY required');
+
+  const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+      'HTTP-Referer': 'https://holoscript.net',
+      'X-Title': 'HoloScript Framework',
+    },
+    body: JSON.stringify({
+      model: config.model,
+      max_tokens: maxTokens,
+      temperature,
+      messages: messages.map(m => ({ role: m.role, content: m.content })),
+    }),
+    signal: AbortSignal.timeout(60_000),
+  });
+
+  if (!res.ok) throw new Error(`OpenRouter API error: ${res.status}`);
+  const data = await res.json() as { choices: Array<{ message: { content: string } }>; usage?: { completion_tokens: number } };
+
+  return {
+    content: data.choices?.[0]?.message?.content || '',
+    model: config.model,
+    provider: 'openrouter',
+    tokensUsed: data.usage?.completion_tokens,
+  };
+}