agentdb 1.5.8 → 1.6.0

package/src/controllers/ContextSynthesizer.ts

@@ -0,0 +1,285 @@
+/**
+ * Context Synthesis - Generate coherent narratives from multiple memories
+ *
+ * Takes a collection of retrieved episodes/patterns and synthesizes
+ * a coherent context summary with extracted patterns, success rates,
+ * and actionable insights.
+ */
+
+export interface MemoryPattern {
+  task: string;
+  reward: number;
+  success: boolean;
+  critique?: string;
+  input?: string;
+  output?: string;
+  similarity?: number;
+  [key: string]: any;
+}
+
+export interface SynthesizedContext {
+  summary: string;
+  patterns: string[];
+  successRate: number;
+  averageReward: number;
+  recommendations: string[];
+  keyInsights: string[];
+  totalMemories: number;
+}
+
+export class ContextSynthesizer {
+  /**
+   * Synthesize context from multiple memories
+   *
+   * @param memories - Retrieved episodes/patterns
+   * @param options - Synthesis options
+   * @returns Synthesized context with insights
+   */
+  static synthesize(
+    memories: MemoryPattern[],
+    options: {
+      minPatternFrequency?: number;
+      includeRecommendations?: boolean;
+      maxSummaryLength?: number;
+    } = {}
+  ): SynthesizedContext {
+    const minPatternFrequency = options.minPatternFrequency ?? 2;
+    const includeRecommendations = options.includeRecommendations ?? true;
+
+    if (memories.length === 0) {
+      return {
+        summary: 'No relevant memories found.',
+        patterns: [],
+        successRate: 0,
+        averageReward: 0,
+        recommendations: [],
+        keyInsights: [],
+        totalMemories: 0,
+      };
+    }
+
+    // Calculate statistics
+    const successCount = memories.filter(m => m.success).length;
+    const successRate = successCount / memories.length;
+    const averageReward = memories.reduce((sum, m) => sum + (m.reward || 0), 0) / memories.length;
+
+    // Extract common patterns from critiques
+    const patterns = this.extractPatterns(memories, minPatternFrequency);
+
+    // Generate key insights
+    const keyInsights = this.generateKeyInsights(memories, successRate, averageReward);
+
+    // Generate recommendations
+    const recommendations = includeRecommendations
+      ? this.generateRecommendations(memories, patterns, successRate)
+      : [];
+
+    // Generate summary narrative
+    const summary = this.generateSummary(memories, patterns, successRate, averageReward);
+
+    return {
+      summary,
+      patterns,
+      successRate,
+      averageReward,
+      recommendations,
+      keyInsights,
+      totalMemories: memories.length,
+    };
+  }
+
+  /**
+   * Extract common patterns from memory critiques
+   */
+  private static extractPatterns(memories: MemoryPattern[], minFrequency: number): string[] {
+    const phraseCount = new Map<string, number>();
+
+    // Extract meaningful phrases from critiques
+    for (const memory of memories) {
+      if (memory.critique) {
+        const phrases = this.extractPhrases(memory.critique);
+        for (const phrase of phrases) {
+          phraseCount.set(phrase, (phraseCount.get(phrase) || 0) + 1);
+        }
+      }
+    }
+
+    // Filter by minimum frequency
+    const patterns: string[] = [];
+    for (const [phrase, count] of phraseCount.entries()) {
+      if (count >= minFrequency) {
+        patterns.push(`${phrase} (${count}/${memories.length} times)`);
+      }
+    }
+
+    return patterns.slice(0, 10);  // Top 10 patterns
+  }
+
+  /**
+   * Extract meaningful phrases from text
+   */
+  private static extractPhrases(text: string): string[] {
+    // Simple phrase extraction (can be enhanced with NLP)
+    const sentences = text.split(/[.!?]/).filter(s => s.trim().length > 0);
+    const phrases: string[] = [];
+
+    for (const sentence of sentences) {
+      const trimmed = sentence.trim();
+      // Extract phrases with key action words
+      if (
+        trimmed.match(/\b(use|implement|fix|improve|add|create|design|test)\b/i) &&
+        trimmed.length > 10 &&
+        trimmed.length < 100
+      ) {
+        phrases.push(trimmed.toLowerCase());
+      }
+    }
+
+    return phrases;
+  }
+
+  /**
+   * Generate key insights from memories
+   */
+  private static generateKeyInsights(
+    memories: MemoryPattern[],
+    successRate: number,
+    averageReward: number
+  ): string[] {
+    const insights: string[] = [];
+
+    // Success rate insight
+    if (successRate >= 0.8) {
+      insights.push(`High success rate (${(successRate * 100).toFixed(0)}%) indicates strong pattern match`);
+    } else if (successRate < 0.5) {
+      insights.push(`Low success rate (${(successRate * 100).toFixed(0)}%) suggests exploring alternative approaches`);
+    }
+
+    // Reward insight
+    if (averageReward >= 0.8) {
+      insights.push(`High average reward (${averageReward.toFixed(2)}) shows effective past solutions`);
+    } else if (averageReward < 0.6) {
+      insights.push(`Moderate reward (${averageReward.toFixed(2)}) indicates room for improvement`);
+    }
+
+    // Identify high-performing memories
+    const topMemories = memories
+      .filter(m => m.success && (m.reward || 0) >= 0.9)
+      .slice(0, 3);
+
+    if (topMemories.length > 0) {
+      insights.push(`${topMemories.length} exemplary solution(s) found with reward ≥0.9`);
+    }
+
+    // Task diversity
+    const uniqueTasks = new Set(memories.map(m => m.task)).size;
+    if (uniqueTasks > 1) {
+      insights.push(`${uniqueTasks} different task types provide diverse perspectives`);
+    }
+
+    return insights;
+  }
+
+  /**
+   * Generate actionable recommendations
+   */
+  private static generateRecommendations(
+    memories: MemoryPattern[],
+    patterns: string[],
+    successRate: number
+  ): string[] {
+    const recommendations: string[] = [];
+
+    // Extract successful strategies
+    const successfulMemories = memories.filter(m => m.success && (m.reward || 0) >= 0.8);
+
+    if (successfulMemories.length > 0) {
+      recommendations.push('Apply strategies from high-reward solutions');
+    }
+
+    // Pattern-based recommendations
+    if (patterns.length > 0) {
+      recommendations.push(`Follow common patterns: ${patterns[0].split(' (')[0]}`);
+    }
+
+    // Success rate recommendations
+    if (successRate >= 0.7) {
+      recommendations.push('Previous approaches were effective - follow similar methodology');
+    } else {
+      recommendations.push('Consider alternative approaches given mixed past results');
+    }
+
+    // Add general recommendations
+    if (memories.length >= 5) {
+      recommendations.push('Sufficient historical data available for confident decision-making');
+    } else {
+      recommendations.push('Limited data - proceed with caution and validate assumptions');
+    }
+
+    return recommendations.slice(0, 5);
+  }
+
+  /**
+   * Generate narrative summary
+   */
+  private static generateSummary(
+    memories: MemoryPattern[],
+    patterns: string[],
+    successRate: number,
+    averageReward: number
+  ): string {
+    const parts: string[] = [];
+
+    // Opening
+    parts.push(`Based on ${memories.length} similar past ${memories.length === 1 ? 'experience' : 'experiences'}`);
+
+    // Success rate
+    const successPercent = (successRate * 100).toFixed(0);
+    if (successRate >= 0.7) {
+      parts.push(`with a high success rate of ${successPercent}%`);
+    } else {
+      parts.push(`with a ${successPercent}% success rate`);
+    }
+
+    // Average reward
+    parts.push(`and average reward of ${averageReward.toFixed(2)}`);
+
+    // Key patterns
+    if (patterns.length > 0) {
+      parts.push('. Common effective approaches include:');
+      const topPatterns = patterns.slice(0, 3).map(p => p.split(' (')[0]);
+      parts.push(topPatterns.map((p, i) => `${i + 1}) ${p}`).join(', '));
+    }
+
+    // High performers
+    const topMemories = memories.filter(m => m.success && (m.reward || 0) >= 0.9);
+    if (topMemories.length > 0) {
+      parts.push(`. ${topMemories.length} exemplary solution(s) achieved reward ≥0.9`);
+    }
+
+    parts.push('.');
+
+    return parts.join(' ');
+  }
+
+  /**
+   * Extract actionable steps from successful memories
+   */
+  static extractActionableSteps(memories: MemoryPattern[]): string[] {
+    const steps: string[] = [];
+    const successfulMemories = memories.filter(m => m.success && (m.reward || 0) >= 0.8);
+
+    for (const memory of successfulMemories) {
+      if (memory.critique) {
+        // Extract step-like phrases
+        const matches = memory.critique.match(/\b\d+\.\s+([^.!?]+)/g);
+        if (matches) {
+          steps.push(...matches.map(m => m.trim()));
+        }
+      }
+    }
+
+    // Remove duplicates and return top 5
+    return Array.from(new Set(steps)).slice(0, 5);
+  }
+}

package/src/controllers/MMRDiversityRanker.ts

@@ -0,0 +1,187 @@
+/**
+ * MMR (Maximal Marginal Relevance) Diversity Ranking
+ *
+ * Implements MMR algorithm to select diverse results that balance
+ * relevance to query with diversity from already-selected results.
+ *
+ * Formula: MMR = argmax [λ × Sim(Di, Q) - (1-λ) × max Sim(Di, Dj)]
+ *                Di∈R\S              Dj∈S
+ *
+ * Where:
+ * - Di = candidate document
+ * - Q = query
+ * - S = already selected documents
+ * - λ = balance parameter (0 = max diversity, 1 = max relevance)
+ */
+
+export interface MMROptions {
+  lambda?: number;  // Balance between relevance and diversity (default: 0.5)
+  k?: number;       // Number of results to return (default: 10)
+  metric?: 'cosine' | 'euclidean' | 'dot';  // Similarity metric
+}
+
+export interface MMRCandidate {
+  id: number;
+  embedding: number[];
+  similarity: number;  // Similarity to query
+  [key: string]: any;  // Additional data
+}
+
+export class MMRDiversityRanker {
+  /**
+   * Select diverse results using MMR algorithm
+   *
+   * @param candidates - All candidate results with embeddings
+   * @param queryEmbedding - Query vector
+   * @param options - MMR configuration
+   * @returns Diverse subset of candidates
+   */
+  static selectDiverse(
+    candidates: MMRCandidate[],
+    queryEmbedding: number[],
+    options: MMROptions = {}
+  ): MMRCandidate[] {
+    const lambda = options.lambda ?? 0.5;
+    const k = options.k ?? 10;
+    const metric = options.metric ?? 'cosine';
+
+    if (candidates.length === 0) {
+      return [];
+    }
+
+    if (candidates.length <= k) {
+      return candidates;
+    }
+
+    // Calculate initial similarities to query
+    const candidatesWithSim = candidates.map(c => ({
+      ...c,
+      similarity: c.similarity ?? this.calculateSimilarity(
+        queryEmbedding,
+        c.embedding,
+        metric
+      ),
+    }));
+
+    const selected: MMRCandidate[] = [];
+    const remaining = [...candidatesWithSim];
+
+    // Select first item (highest relevance)
+    remaining.sort((a, b) => b.similarity - a.similarity);
+    selected.push(remaining.shift()!);
+
+    // Iteratively select items with highest MMR score
+    while (selected.length < k && remaining.length > 0) {
+      let maxMMR = -Infinity;
+      let maxIdx = 0;
+
+      for (let i = 0; i < remaining.length; i++) {
+        const candidate = remaining[i];
+
+        // Calculate max similarity to already-selected items
+        let maxSimToSelected = -Infinity;
+        for (const selectedItem of selected) {
+          const sim = this.calculateSimilarity(
+            candidate.embedding,
+            selectedItem.embedding,
+            metric
+          );
+          maxSimToSelected = Math.max(maxSimToSelected, sim);
+        }
+
+        // Calculate MMR score
+        const mmrScore = lambda * candidate.similarity - (1 - lambda) * maxSimToSelected;
+
+        if (mmrScore > maxMMR) {
+          maxMMR = mmrScore;
+          maxIdx = i;
+        }
+      }
+
+      // Add item with highest MMR score
+      selected.push(remaining.splice(maxIdx, 1)[0]);
+    }
+
+    return selected;
+  }
+
+  /**
+   * Calculate similarity between two vectors
+   */
+  private static calculateSimilarity(
+    vec1: number[],
+    vec2: number[],
+    metric: 'cosine' | 'euclidean' | 'dot'
+  ): number {
+    if (vec1.length !== vec2.length) {
+      throw new Error(`Vector dimension mismatch: ${vec1.length} vs ${vec2.length}`);
+    }
+
+    switch (metric) {
+      case 'cosine': {
+        let dot = 0, mag1 = 0, mag2 = 0;
+        for (let i = 0; i < vec1.length; i++) {
+          dot += vec1[i] * vec2[i];
+          mag1 += vec1[i] * vec1[i];
+          mag2 += vec2[i] * vec2[i];
+        }
+        return dot / (Math.sqrt(mag1) * Math.sqrt(mag2));
+      }
+
+      case 'euclidean': {
+        let sum = 0;
+        for (let i = 0; i < vec1.length; i++) {
+          const diff = vec1[i] - vec2[i];
+          sum += diff * diff;
+        }
+        return 1 / (1 + Math.sqrt(sum));  // Normalized to 0-1
+      }
+
+      case 'dot': {
+        let dot = 0;
+        for (let i = 0; i < vec1.length; i++) {
+          dot += vec1[i] * vec2[i];
+        }
+        return dot;
+      }
+
+      default:
+        throw new Error(`Unknown metric: ${metric}`);
+    }
+  }
+
+  /**
+   * Calculate diversity score for a set of results
+   *
+   * @param results - Results to analyze
+   * @param metric - Similarity metric
+   * @returns Average pairwise distance (higher = more diverse)
+   */
+  static calculateDiversityScore(
+    results: MMRCandidate[],
+    metric: 'cosine' | 'euclidean' | 'dot' = 'cosine'
+  ): number {
+    if (results.length < 2) {
+      return 1.0;  // Single result is maximally diverse
+    }
+
+    let totalDistance = 0;
+    let comparisons = 0;
+
+    for (let i = 0; i < results.length; i++) {
+      for (let j = i + 1; j < results.length; j++) {
+        const similarity = this.calculateSimilarity(
+          results[i].embedding,
+          results[j].embedding,
+          metric
+        );
+        // Convert similarity to distance
+        const distance = metric === 'cosine' ? 1 - similarity : similarity;
+        totalDistance += distance;
+        comparisons++;
+      }
+    }
+
+    return comparisons > 0 ? totalDistance / comparisons : 0;
+  }
+}