@yun520-1/heartflow 0.15.2

package/src/core/self-evolution/reflexion-prompts.mjs

@@ -0,0 +1,284 @@
+/**
+ * Reflexion Skill Prompts - Few-shot prompt templates
+ * 
+ * Ports the core few-shot patterns from Reflexion (noahshinn/reflexion)
+ * adapted for HeartFlow skill authoring and code improvement.
+ * 
+ * Key insight from Reflexion:
+ * The "simple" strategy: direct generation
+ * The "reflexion" strategy: [prev_impl] + [test_results] + [reflection] → [improved]
+ * 
+ * @version v0.13.90
+ */
+
+// ============================================================================
+// System Instructions
+// ============================================================================
+
+/**
+ * Base system instruction for skill authoring
+ */
+export const SKILL_AUTHOR_INSTRUCTION = `You are a HeartFlow skill author. You write high-quality, actionable skill definitions.
+
+Quality standards:
+- Each skill has a clear trigger condition (what situation activates it)
+- Guidance is specific and actionable (not vague suggestions)
+- Examples are concrete (actual inputs that trigger the skill)
+- Anti-patterns identify what NOT to do
+
+Output format: JSON skill definition.`;
+
+/**
+ * System instruction for code improvement using reflection
+ */
+export const CODE_IMPROVE_INSTRUCTION = `You are a code improvement specialist using verbal reinforcement learning.
+
+Your task: Given a previous implementation, test results, and self-reflection,
+write an improved version that addresses the failures.
+
+The reflection tells you WHAT went wrong. Your job is to fix it.`;
+
+// ============================================================================
+// Reflexion Few-Shot Templates
+// ============================================================================
+
+/**
+ * Reflection prompt - generates verbal reinforcement cue
+ * This is the "Msr" component of Reflexion
+ * 
+ * @param {string} funcImpl - Previous code implementation
+ * @param {string} feedback - Test results / error output
+ * @param {string} [fewShot] - Optional few-shot examples
+ */
+export function buildReflectionPrompt(funcImpl, feedback, fewShot) {
+  const base = `[function impl]:
+${funcImpl}
+
+[unit test results]:
+${feedback}
+
+[self-reflection]:`;
+
+  if (fewShot) {
+    return `${fewShot}
+
+${base}`;
+  }
+
+  return base;
+}
+
+/**
+ * Code improvement prompt - generates improved implementation
+ * The "actor" component that uses reflection to improve
+ * 
+ * @param {string} funcSig - Function signature / task description
+ * @param {string} prevImpl - Previous implementation
+ * @param {string} feedback - Test results
+ * @param {string} reflection - Self-reflection analysis
+ * @param {string} [fewShot] - Optional few-shot examples
+ */
+export function buildImprovePrompt(funcSig, prevImpl, feedback, reflection, fewShot) {
+  const base = `${CODE_IMPROVE_INSTRUCTION}
+
+[previous impl]:
+${prevImpl}
+
+unit tests:
+${feedback}
+
+hint:
+${reflection}
+
+# improved implementation
+${funcSig}`;
+
+  if (fewShot) {
+    return `${fewShot}
+
+${base}`;
+  }
+
+  return base;
+}
+
+/**
+ * Skill improvement prompt - for improving skill definitions
+ * 
+ * @param {Object} params
+ * @param {string} params.skillName
+ * @param {string} params.currentDef
+ * @param {string} params.errorFeedback
+ * @param {string} params.correction
+ */
+export function buildSkillImprovePrompt({ skillName, currentDef, errorFeedback, correction }) {
+  return `${SKILL_AUTHOR_INSTRUCTION}
+
+Task: Improve the skill definition for "${skillName}" based on error feedback.
+
+Current definition:
+${currentDef}
+
+Error feedback:
+${errorFeedback}
+
+Correction:
+${correction}
+
+Write the improved skill definition in JSON format.`;
+}
+
+/**
+ * Generate self-reflection for a skill definition
+ * @param {string} skillDef
+ * @param {string} testFeedback
+ */
+export function buildSkillReflectionPrompt(skillDef, testFeedback) {
+  return `Analyze this skill definition and provide a self-reflection:
+
+Skill:
+${skillDef}
+
+Test/use feedback:
+${testFeedback}
+
+Output 2-3 sentences: what went wrong with this skill definition and exactly how to fix it.`;
+}
+
+// ============================================================================
+// Simple Generation (no reflection)
+// ============================================================================
+
+/**
+ * Simple code generation prompt (no reflection)
+ * @param {string} funcSig
+ * @param {string} [fewShot]
+ */
+export function buildSimplePrompt(funcSig, fewShot) {
+  const base = `Write the code implementation for:
+
+${funcSig}
+
+Only output the code, no explanations.`;
+
+  if (fewShot) {
+    return `${fewShot}
+
+${base}`;
+  }
+
+  return base;
+}
+
+/**
+ * Simple skill generation prompt
+ * @param {string} taskDescription
+ */
+export function buildSimpleSkillPrompt(taskDescription) {
+  return `${SKILL_AUTHOR_INSTRUCTION}
+
+Task: Create a skill for: ${taskDescription}
+
+Output in JSON format with: name, trigger, guidance, examples, anti_patterns.`;
+}
+
+// ============================================================================
+// Quality Gate Prompts (CAPY Cortex inspired)
+// ============================================================================
+
+/**
+ * Evaluate an insight across 4 dimensions
+ * @param {string} insight
+ */
+export function buildInsightEvalPrompt(insight) {
+  return `Evaluate this insight across 4 dimensions (score 0-4 each):
+1. ACTIONABLE: Does it tell you WHAT to do specifically?
+2. SPECIFIC: Does it contain concrete details (code, file, error, command)?
+3. NOVEL: Does it provide new information beyond the obvious?
+4. DURABLE: Does it apply broadly, not just to this one case?
+
+Insight: "${insight}"
+
+Output JSON: {"actionable": N, "specific": N, "novel": N, "durable": N}
+Score 0 = completely fails dimension, 4 = perfectly meets dimension.`;
+}
+
+// ============================================================================
+// Root Cause Analysis (for onToolFailure hook)
+// ============================================================================
+
+/**
+ * Root cause analysis prompt
+ * @param {string} action
+ * @param {string} error
+ */
+export function buildRootCausePrompt(action, error) {
+  return `You are a root-cause analyst for HeartFlow.
+
+Action: ${action}
+
+Error: ${error}
+
+Identify the PRECISE cause of failure in 1-2 sentences. Be specific about which step failed and why.`;
+}
+
+/**
+ * Correction generation prompt
+ * @param {string} action
+ * @param {string} error
+ * @param {string} rootCause
+ */
+export function buildCorrectionPrompt(action, error, rootCause) {
+  return `You are a technical mentor for HeartFlow.
+
+Failed action: ${action}
+Error: ${error}
+Root cause: ${rootCause}
+
+Give ONE specific, actionable correction to fix this. No preamble, just the fix.`;
+}
+
+// ============================================================================
+// Dash-style Context Building
+// ============================================================================
+
+/**
+ * Build context for system prompt (Dash add_learnings_to_context pattern)
+ * @param {Array<{pattern: string, guidance: string}>} matched
+ * @param {Array<{errorPattern: string, correction: string, confidence: number}>} learnings
+ */
+export function buildSystemContext(matched = [], learnings = []) {
+  const lines = [];
+
+  if (matched.length > 0) {
+    lines.push('## SKILL RULES (curated)');
+    for (const m of matched) {
+      lines.push(`- ${m.pattern}: ${m.guidance}`);
+    }
+  }
+
+  if (learnings.length > 0) {
+    lines.push('\n## LEARNED PATTERNS (from past errors)');
+    for (const l of learnings) {
+      const pct = Math.round(l.confidence * 100);
+      lines.push(`- [${pct}%] ${l.errorPattern}: ${l.correction}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export default {
+  SKILL_AUTHOR_INSTRUCTION,
+  CODE_IMPROVE_INSTRUCTION,
+  buildReflectionPrompt,
+  buildImprovePrompt,
+  buildSkillImprovePrompt,
+  buildSkillReflectionPrompt,
+  buildSimplePrompt,
+  buildSimpleSkillPrompt,
+  buildInsightEvalPrompt,
+  buildRootCausePrompt,
+  buildCorrectionPrompt,
+  buildSystemContext,
+};

package/src/core/self-evolution/reflexion-v2.mjs

@@ -0,0 +1,427 @@
+/**
+ * Reflexion v2 - HeartFlow Integration
+ * Based on Reflexion-TS (faveos8758/reflexion-agent-ts) + Reflexion (noahshinn/reflexion)
+ * 
+ * Core improvements over v1:
+ * - LLM-powered reflector (not heuristic)
+ * - Jaccard similarity memory (not raw array)
+ * - Quality gate: 2/4 threshold filtering
+ * - Type-safe ESM module
+ * 
+ * @version v0.13.89
+ */
+
+import { promises as fs } from 'fs';
+import { dirname } from 'path';
+
+// ============================================================================
+// Types (from Reflexion-TS)
+// ============================================================================
+
+/**
+ * @typedef {Object} MemoryEntry
+ * @property {string} task
+ * @property {string} promptSummary
+ * @property {string} failedOutput
+ * @property {string} feedback
+ * @property {number} createdAt
+ */
+
+/**
+ * @typedef {Object} MemoryQuery
+ * @property {string} task
+ * @property {string} prompt
+ * @property {number} [limit]
+ */
+
+/**
+ * @typedef {Object} EvaluatorResult
+ * @property {boolean} passed
+ * @property {number} [score]
+ * @property {string} [reason]
+ */
+
+/**
+ * @typedef {function(string, string, string): Promise<string>} ReflectorFunction
+ * @typedef {function(string, unknown?): Promise<EvaluatorResult>} EvaluatorFunction
+ */
+
+// ============================================================================
+// Jaccard Similarity Memory (from Reflexion-TS, cleaned)
+// ============================================================================
+
+/**
+ * Tokenize text into word set
+ * @param {string} s 
+ * @returns {Set<string>}
+ */
+function tokenize(s) {
+  return new Set((s.toLowerCase().match(/\w+/g) ?? []));
+}
+
+/**
+ * Jaccard similarity between two sets
+ * @param {Set<string>} a 
+ * @param {Set<string>} b 
+ * @returns {number}
+ */
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 1;
+  let inter = 0;
+  for (const t of a) {
+    if (b.has(t)) inter++;
+  }
+  const union = a.size + b.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+
+/**
+ * Compute similarity between query and memory entry
+ * @param {string} prompt 
+ * @param {MemoryEntry} entry 
+ * @returns {number}
+ */
+function similarity(prompt, entry) {
+  const q = tokenize(prompt);
+  const p = tokenize(entry.promptSummary);
+  const f = tokenize(entry.feedback);
+  return jaccard(q, p) * 0.7 + jaccard(q, f) * 0.3;
+}
+
+/**
+ * In-memory reflexion store with Jaccard similarity retrieval.
+ * No external vector DB required.
+ */
+export class ReflexionMemory {
+  constructor() {
+    /** @type {MemoryEntry[]} */
+    this.entries = [];
+  }
+
+  /**
+   * Store a new memory entry
+   * @param {Omit<MemoryEntry, 'createdAt'> & { createdAt?: number }} entry
+   */
+  async store(entry) {
+    const full = {
+      ...entry,
+      createdAt: entry.createdAt ?? Date.now(),
+    };
+    this.entries.push(full);
+  }
+
+  /**
+   * Retrieve similar memories by prompt
+   * @param {MemoryQuery} query
+   * @returns {Promise<string[]>}
+   */
+  async retrieveSimilar(query) {
+    const limit = query.limit ?? 5;
+    const sameTask = this.entries.filter((e) => e.task === query.task);
+    const scored = sameTask
+      .map((e) => ({ e, s: similarity(query.prompt, e) }))
+      .sort((a, b) => b.s - a.s)
+      .slice(0, limit)
+      .map((x) => x.e.feedback);
+    return scored;
+  }
+
+  /**
+   * Save memories to file (JSON)
+   * @param {string} path
+   */
+  async saveToFile(path) {
+    await fs.mkdir(dirname(path), { recursive: true });
+    const data = JSON.stringify({ entries: this.entries }, null, 2);
+    await fs.writeFile(path, data, 'utf8');
+  }
+
+  /**
+   * Load memories from file
+   * @param {string} path
+   */
+  async loadFromFile(path) {
+    try {
+      const raw = await fs.readFile(path, 'utf8');
+      const parsed = JSON.parse(raw);
+      this.entries = Array.isArray(parsed.entries) ? parsed.entries : [];
+    } catch {
+      this.entries = [];
+    }
+  }
+
+  /** @param {number} maxEntries */
+  trim(maxEntries = 1000) {
+    if (this.entries.length > maxEntries) {
+      this.entries = this.entries.slice(-maxEntries);
+    }
+  }
+
+  clear() {
+    this.entries = [];
+  }
+
+  get size() {
+    return this.entries.length;
+  }
+}
+
+// ============================================================================
+// LLM Reflector (from Reflexion-TS, enhanced)
+// ============================================================================
+
+/**
+ * Create default LLM-based reflector
+ * Uses HeartFlow's LLM API (generic, works with any provider)
+ * 
+ * @param {function(string, string): Promise<string>} llmCall - LLM function: (system, prompt) => text
+ * @returns {ReflectorFunction}
+ */
+export function createLLMReflector(llmCall) {
+  return async (originalPrompt, failedOutput, evaluationReason) => {
+    const system = `You write concise reflective feedback for a failed attempt. Be specific: what went wrong and what to do next time. Output only the feedback, no preamble.`;
+    const prompt = `Original task:
+${originalPrompt}
+
+Failed output:
+${failedOutput}
+
+Evaluation:
+${evaluationReason}
+
+Write 2-4 sentences: what went wrong and exactly what to do next time.`;
+
+    try {
+      const text = await llmCall(system, prompt);
+      return text.trim();
+    } catch (err) {
+      return `Reflection failed: ${err.message}. Next time, verify output before proceeding.`;
+    }
+  };
+}
+
+/**
+ * Template-based reflector (fallback when no LLM available)
+ * @returns {ReflectorFunction}
+ */
+export function createTemplateReflector() {
+  return async (_originalPrompt, failedOutput, evaluationReason) =>
+    `You failed because: ${evaluationReason}. Your output was: ${failedOutput.slice(0, 200)}${failedOutput.length > 200 ? '…' : ''}. Next time, address the evaluation feedback precisely.`;
+}
+
+// ============================================================================
+// Quality Gate (from CAPY Cortex)
+// ============================================================================
+
+/**
+ * Quality dimensions for extracted insights
+ * @typedef {{ actionable: number, specific: number, novel: number, durable: number }} QualityScore
+ */
+
+/**
+ * Score an insight across 4 dimensions (0-4 each)
+ * @param {string} insight
+ * @param {string} context
+ * @returns {QualityScore}
+ */
+export function scoreInsight(insight, context = '') {
+  const words = insight.split(/\s+/);
+  const uniqueWords = new Set(words.map(w => w.toLowerCase()));
+  
+  // Actionable: contains verbs, recommendations
+  const actionable = /should|must|try|use|apply|instead|rather|better|alternative/i.test(insight) ? 3 : 1;
+  
+  // Specific: contains concrete details (not vague)
+  const specific = (insight.match(/\d+|code|file|error|function|command|path/i) || []).length > 2 ? 3 : 1;
+  
+  // Novel: not just repeating context
+  const contextWords = new Set(context.toLowerCase().split(/\s+/));
+  let novelCount = 0;
+  for (const w of uniqueWords) {
+    if (w.length > 4 && !contextWords.has(w)) novelCount++;
+  }
+  const novel = novelCount > words.length * 0.3 ? 3 : 1;
+  
+  // Durable: not time-specific or one-shot
+  const durable = /\balways|never|whenever|if.*then|consistent/i.test(insight) ? 3 : 1;
+  
+  return { actionable, specific, novel, durable };
+}
+
+/**
+ * Check if insight passes quality gate (threshold: 2/4 average)
+ * @param {QualityScore} score
+ * @returns {boolean}
+ */
+export function passesGate(score) {
+  const avg = (score.actionable + score.specific + score.novel + score.durable) / 4;
+  return avg >= 2;
+}
+
+// ============================================================================
+// Reflexion Agent (HeartFlow-native implementation)
+// ============================================================================
+
+/**
+ * Normalize maxAttempts to valid integer
+ * @param {unknown} raw
+ * @returns {number}
+ */
+function normalizeMaxAttempts(raw) {
+  const n = typeof raw === 'number' ? raw
+    : typeof raw === 'string' ? Number.parseInt(raw, 10)
+    : NaN;
+  if (!Number.isFinite(n) || n < 1) return 3;
+  return Math.min(50, Math.floor(n));
+}
+
+/**
+ * Reflexion Agent - Main Loop
+ * 
+ * Pattern: Attempt -> Evaluate -> Reflect (if failed) -> Retry
+ * Until success or maxAttempts
+ * 
+ * @property {string} task
+ * @property {number} maxAttempts
+ * @property {EvaluatorFunction} evaluator
+ * @property {ReflectorFunction} reflector
+ * @property {ReflexionMemory} memory
+ */
+export class HeartFlowReflexionAgent {
+  /**
+   * @param {{
+   *   task: string,
+   *   maxAttempts?: number|string,
+   *   evaluator: EvaluatorFunction,
+   *   reflector?: ReflectorFunction,
+   *   memory?: ReflexionMemory,
+   *   onAttempt?: (attempt: number, output: string, feedback?: string) => void,
+   * }} config
+   */
+  constructor(config) {
+    this.task = config.task;
+    this.maxAttempts = normalizeMaxAttempts(config.maxAttempts ?? 3);
+    this.evaluator = config.evaluator;
+    this.reflector = config.reflector ?? createTemplateReflector();
+    this.memory = config.memory ?? new ReflexionMemory();
+    this.onAttempt = config.onAttempt ?? (() => {});
+    this._attemptCount = 0;
+  }
+
+  /**
+   * Run the reflexion loop
+   * @param {string} prompt
+   * @param {function(string): Promise<{ text: string, done?: boolean }>} executor
+   * @returns {Promise<{ success: boolean, output: string, attempts: number, feedbackHistory: string[] }>}
+   */
+  async run(prompt, executor) {
+    let output = '';
+    const feedbackHistory = [];
+    let finalFeedback;
+    this._attemptCount = 0;
+
+    // Retrieve similar past reflections for context
+    const similar = await this.memory.retrieveSimilar({
+      task: this.task,
+      prompt,
+      limit: 3,
+    });
+
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+      this._attemptCount = attempt;
+
+      // Generate output
+      const result = await executor(prompt);
+      output = result.text;
+
+      // Evaluate
+      const evalResult = await this.evaluator(output);
+      this.onAttempt(attempt, output, evalResult.reason);
+
+      if (evalResult.passed) {
+        return {
+          success: true,
+          output,
+          attempts: attempt,
+          feedbackHistory,
+        };
+      }
+
+      // Generate reflection
+      const reflection = await this.reflector(prompt, output, evalResult.reason ?? 'Evaluation failed');
+      feedbackHistory.push(reflection);
+      finalFeedback = reflection;
+
+      // Store in memory with quality gate
+      const score = scoreInsight(reflection, prompt + output);
+      if (passesGate(score)) {
+        await this.memory.store({
+          task: this.task,
+          promptSummary: prompt.slice(0, 100),
+          failedOutput: output.slice(0, 500),
+          feedback: reflection,
+        });
+      }
+    }
+
+    return {
+      success: false,
+      output,
+      attempts: this._attemptCount,
+      feedbackHistory,
+      finalFeedback,
+    };
+  }
+}
+
+// ============================================================================
+// Factory for HeartFlow integration
+// ============================================================================
+
+/**
+ * Create a reflexion agent configured for HeartFlow
+ * 
+ * @param {{
+ *   task: string,
+ *   llmCall?: function(string, string): Promise<string>,
+ *   evaluatorFn?: EvaluatorFunction,
+ *   memoryFile?: string,
+ * }} options
+ */
+export function createHeartFlowReflexion(options) {
+  const memory = new ReflexionMemory();
+  
+  // Load existing memory if file provided
+  if (options.memoryFile) {
+    memory.loadFromFile(options.memoryFile).catch(() => {});
+  }
+
+  // Default evaluator: checks for error indicators
+  const defaultEvaluator = async (output) => {
+    const hasError = /\b(error|failed|exception|crash|wrong|incorrect)\b/i.test(output);
+    const hasSuccess = /\b(success|complete|done|working|correct)\b/i.test(output);
+    return {
+      passed: hasSuccess && !hasError,
+      score: hasSuccess && !hasError ? 1 : 0,
+      reason: hasError ? 'Output contains error indicators' : hasSuccess ? 'Output looks good' : 'No clear success/error signal',
+    };
+  };
+
+  return new HeartFlowReflexionAgent({
+    task: options.task,
+    maxAttempts: options.maxAttempts ?? 3,
+    evaluator: options.evaluatorFn ?? defaultEvaluator,
+    reflector: options.llmCall ? createLLMReflector(options.llmCall) : createTemplateReflector(),
+    memory,
+  });
+}
+
+export default {
+  ReflexionMemory,
+  HeartFlowReflexionAgent,
+  createLLMReflector,
+  createTemplateReflector,
+  createHeartFlowReflexion,
+  scoreInsight,
+  passesGate,
+};