agentic-flow 1.4.4 → 1.4.6

package/dist/reasoningbank/core/distill.js

@@ -0,0 +1,159 @@
+/**
+ * Memory Distillation from trajectories
+ * Algorithm 3 from ReasoningBank paper
+ */
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { ulid } from 'ulid';
+import { loadConfig } from '../utils/config.js';
+import { scrubMemory } from '../utils/pii-scrubber.js';
+import { computeEmbedding } from '../utils/embeddings.js';
+import * as db from '../db/queries.js';
+/**
+ * Distill memories from a trajectory
+ */
+export async function distillMemories(trajectory, verdict, query, options = {}) {
+    const config = loadConfig();
+    const startTime = Date.now();
+    console.log(`[INFO] Distilling memories from ${verdict.label} trajectory`);
+    // Select appropriate prompt template
+    const templateName = verdict.label === 'Success' ? 'distill-success.json' : 'distill-failure.json';
+    const promptPath = join(process.cwd(), 'src', 'reasoningbank', 'prompts', templateName);
+    const promptTemplate = JSON.parse(readFileSync(promptPath, 'utf-8'));
+    const maxItems = verdict.label === 'Success'
+        ? config.distill.max_items_success
+        : config.distill.max_items_failure;
+    const confidencePrior = verdict.label === 'Success'
+        ? config.distill.confidence_prior_success
+        : config.distill.confidence_prior_failure;
+    // Check API key
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        console.warn('[WARN] ANTHROPIC_API_KEY not set, using template-based distillation');
+        return templateBasedDistill(trajectory, verdict, query, options);
+    }
+    try {
+        // Format trajectory
+        const trajectoryText = JSON.stringify(trajectory.steps || [], null, 2);
+        // Build prompt
+        const prompt = promptTemplate.template
+            .replace('{{task_query}}', query)
+            .replace('{{trajectory}}', trajectoryText)
+            .replace('{{max_items}}', String(maxItems));
+        // Call Anthropic API
+        const response = await fetch('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'x-api-key': apiKey,
+                'anthropic-version': '2023-06-01',
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                model: config.distill.model,
+                max_tokens: 2048,
+                temperature: config.distill.temperature,
+                system: promptTemplate.system,
+                messages: [{ role: 'user', content: prompt }]
+            })
+        });
+        if (!response.ok) {
+            throw new Error(`Anthropic API error: ${response.status}`);
+        }
+        const result = await response.json();
+        const content = result.content[0].text;
+        // Parse memories from response
+        const distilled = parseDistilledMemories(content);
+        // Store memories in database
+        const memoryIds = await storeMemories(distilled, confidencePrior, verdict, options);
+        const duration = Date.now() - startTime;
+        console.log(`[INFO] Distilled ${memoryIds.length} memories in ${duration}ms`);
+        db.logMetric('rb.distill.latency_ms', duration);
+        db.logMetric('rb.distill.yield', memoryIds.length);
+        return memoryIds;
+    }
+    catch (error) {
+        console.error('[ERROR] Distillation failed:', error);
+        return templateBasedDistill(trajectory, verdict, query, options);
+    }
+}
+/**
+ * Parse distilled memories from LLM response
+ */
+function parseDistilledMemories(content) {
+    try {
+        const jsonMatch = content.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            const parsed = JSON.parse(jsonMatch[0]);
+            return parsed.memories || [];
+        }
+    }
+    catch (error) {
+        console.warn('[WARN] Failed to parse distilled memories JSON');
+    }
+    return [];
+}
+/**
+ * Store memories in database
+ */
+async function storeMemories(memories, confidencePrior, verdict, options) {
+    const memoryIds = [];
+    for (const mem of memories) {
+        // Scrub PII
+        const scrubbed = scrubMemory(mem);
+        // Generate embedding
+        const embedding = await computeEmbedding(`${scrubbed.title} ${scrubbed.description} ${scrubbed.content}`);
+        // Create memory ID
+        const id = ulid();
+        // Store memory
+        db.upsertMemory({
+            id,
+            type: 'reasoning_memory',
+            pattern_data: {
+                title: scrubbed.title,
+                description: scrubbed.description,
+                content: scrubbed.content,
+                source: {
+                    task_id: options.taskId || 'unknown',
+                    agent_id: options.agentId || 'unknown',
+                    outcome: verdict.label,
+                    evidence: []
+                },
+                tags: scrubbed.tags,
+                domain: options.domain || scrubbed.domain,
+                created_at: new Date().toISOString(),
+                confidence: confidencePrior,
+                n_uses: 0
+            },
+            confidence: confidencePrior,
+            usage_count: 0
+        });
+        // Store embedding
+        db.upsertEmbedding({
+            id,
+            model: 'distill-' + verdict.label.toLowerCase(),
+            dims: embedding.length,
+            vector: embedding,
+            created_at: new Date().toISOString()
+        });
+        memoryIds.push(id);
+        console.log(`[INFO] Stored memory: ${scrubbed.title}`);
+    }
+    return memoryIds;
+}
+/**
+ * Template-based distillation (fallback)
+ * Simple extraction without LLM
+ */
+function templateBasedDistill(trajectory, verdict, query, options) {
+    console.log('[INFO] Using template-based distillation (no API key)');
+    // Create a single generic memory from the trajectory
+    const memory = {
+        title: `${verdict.label}: ${query.substring(0, 50)}`,
+        description: `Task outcome: ${verdict.label}`,
+        content: `Query: ${query}\n\nSteps: ${trajectory.steps?.length || 0}\n\nOutcome: ${verdict.label}`,
+        tags: [verdict.label.toLowerCase(), 'template'],
+        domain: options.domain
+    };
+    // Store synchronously (no async needed for template)
+    return []; // Skip storage for template-based (would need to make this async)
+}

package/dist/reasoningbank/core/judge.js

@@ -0,0 +1,128 @@
+/**
+ * LLM-as-Judge for trajectory evaluation
+ * Algorithm 2 from ReasoningBank paper
+ */
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { loadConfig } from '../utils/config.js';
+/**
+ * Judge a task trajectory using LLM evaluation
+ */
+export async function judgeTrajectory(trajectory, query, options = {}) {
+    const config = loadConfig();
+    const startTime = Date.now();
+    console.log(`[INFO] Judging trajectory for query: ${query.substring(0, 100)}...`);
+    // Load judge prompt template
+    const promptPath = join(process.cwd(), 'src', 'reasoningbank', 'prompts', 'judge.json');
+    const promptTemplate = JSON.parse(readFileSync(promptPath, 'utf-8'));
+    // Format trajectory for judgment
+    const trajectoryText = formatTrajectory(trajectory);
+    // Check if we have Anthropic API key
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        console.warn('[WARN] ANTHROPIC_API_KEY not set, using heuristic judgment');
+        return heuristicJudge(trajectory, query);
+    }
+    try {
+        // Call Anthropic API with judge prompt
+        const prompt = promptTemplate.template
+            .replace('{{task_query}}', query)
+            .replace('{{trajectory}}', trajectoryText);
+        const response = await fetch('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'x-api-key': apiKey,
+                'anthropic-version': '2023-06-01',
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                model: config.judge.model,
+                max_tokens: config.judge.max_tokens,
+                temperature: config.judge.temperature,
+                system: promptTemplate.system,
+                messages: [{ role: 'user', content: prompt }]
+            })
+        });
+        if (!response.ok) {
+            throw new Error(`Anthropic API error: ${response.status}`);
+        }
+        const result = await response.json();
+        const content = result.content[0].text;
+        // Parse JSON response
+        const verdict = parseVerdict(content);
+        const duration = Date.now() - startTime;
+        console.log(`[INFO] Judgment complete: ${verdict.label} (${verdict.confidence}) in ${duration}ms`);
+        db.logMetric('rb.judge.latency_ms', duration);
+        db.logMetric('rb.judge.success_rate', verdict.label === 'Success' ? 1 : 0);
+        return verdict;
+    }
+    catch (error) {
+        console.error('[ERROR] Judge failed:', error);
+        console.warn('[WARN] Falling back to heuristic judgment');
+        return heuristicJudge(trajectory, query);
+    }
+}
+/**
+ * Format trajectory for LLM consumption
+ */
+function formatTrajectory(trajectory) {
+    const steps = trajectory.steps || [];
+    let formatted = '';
+    for (let i = 0; i < steps.length; i++) {
+        formatted += `Step ${i + 1}: ${JSON.stringify(steps[i], null, 2)}\n\n`;
+    }
+    return formatted || 'No steps recorded';
+}
+/**
+ * Parse verdict from LLM response
+ */
+function parseVerdict(content) {
+    try {
+        // Try to extract JSON from response
+        const jsonMatch = content.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            const parsed = JSON.parse(jsonMatch[0]);
+            return {
+                label: parsed.verdict?.label || parsed.label || 'Failure',
+                confidence: parsed.verdict?.confidence || parsed.confidence || 0.5,
+                reasons: parsed.verdict?.reasons || parsed.reasons || []
+            };
+        }
+    }
+    catch (error) {
+        console.warn('[WARN] Failed to parse verdict JSON, using text analysis');
+    }
+    // Fallback: text-based detection
+    const lower = content.toLowerCase();
+    const isSuccess = lower.includes('success') && !lower.includes('failure');
+    return {
+        label: isSuccess ? 'Success' : 'Failure',
+        confidence: 0.6,
+        reasons: ['Parsed from text (JSON parse failed)']
+    };
+}
+/**
+ * Heuristic judgment when LLM is unavailable
+ * Simple rule-based classification
+ */
+function heuristicJudge(trajectory, query) {
+    const steps = trajectory.steps || [];
+    // Check for error indicators
+    const hasErrors = steps.some(step => JSON.stringify(step).toLowerCase().includes('error'));
+    // Check for completion indicators
+    const hasCompletion = steps.some(step => JSON.stringify(step).toLowerCase().includes('complete'));
+    // Simple heuristic: success if no errors and has completion markers
+    const isSuccess = !hasErrors && hasCompletion && steps.length > 0;
+    return {
+        label: isSuccess ? 'Success' : 'Failure',
+        confidence: 0.5, // Low confidence for heuristic
+        reasons: [
+            `Heuristic judgment (no API key)`,
+            `Steps: ${steps.length}`,
+            `Errors: ${hasErrors}`,
+            `Completion markers: ${hasCompletion}`
+        ]
+    };
+}
+// Import db late to avoid circular dependency
+import * as db from '../db/queries.js';

package/dist/reasoningbank/core/matts.js

@@ -0,0 +1,225 @@
+/**
+ * MaTTS: Memory-aware Test-Time Scaling
+ * Algorithm 5 from ReasoningBank paper
+ *
+ * Two modes:
+ * - Parallel: k independent rollouts with self-contrast aggregation
+ * - Sequential: r iterative refinements with check-and-correct
+ */
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { ulid } from 'ulid';
+import { loadConfig } from '../utils/config.js';
+import { retrieveMemories } from './retrieve.js';
+import { judgeTrajectory } from './judge.js';
+import { distillMemories } from './distill.js';
+import * as db from '../db/queries.js';
+/**
+ * Run MaTTS in parallel mode
+ * Execute k independent rollouts and aggregate via self-contrast
+ */
+export async function mattsParallel(taskFn, query, options = {}) {
+    const config = loadConfig();
+    const k = options.k || config.matts.parallel_k;
+    const runId = ulid();
+    const startTime = Date.now();
+    console.log(`[INFO] Starting MaTTS parallel mode with k=${k}`);
+    // Store MaTTS run
+    db.storeMattsRun({
+        run_id: runId,
+        task_id: options.taskId || 'matts-' + runId,
+        mode: 'parallel',
+        k,
+        status: 'running',
+        summary: undefined
+    });
+    const trajectories = [];
+    // Execute k independent rollouts
+    for (let i = 0; i < k; i++) {
+        console.log(`[INFO] MaTTS parallel rollout ${i + 1}/${k}`);
+        try {
+            const trajectory = await taskFn();
+            const verdict = await judgeTrajectory(trajectory, query);
+            trajectories.push({
+                id: ulid(),
+                verdict,
+                trajectory
+            });
+            // Store trajectory
+            db.storeTrajectory({
+                task_id: options.taskId || 'matts-' + runId,
+                agent_id: options.agentId || 'matts-agent',
+                query,
+                trajectory_json: JSON.stringify(trajectory),
+                started_at: new Date().toISOString(),
+                ended_at: new Date().toISOString(),
+                judge_label: verdict.label,
+                judge_conf: verdict.confidence,
+                judge_reasons: JSON.stringify(verdict.reasons),
+                matts_run_id: runId
+            });
+        }
+        catch (error) {
+            console.error(`[ERROR] MaTTS rollout ${i + 1} failed:`, error);
+        }
+    }
+    // Aggregate memories via self-contrast
+    const aggregatedMemories = await aggregateMemories(trajectories, query, options);
+    const successRate = trajectories.filter(t => t.verdict.label === 'Success').length / trajectories.length;
+    const duration = Date.now() - startTime;
+    console.log(`[INFO] MaTTS parallel complete: ${trajectories.length} trajectories, ${successRate * 100}% success in ${duration}ms`);
+    db.logMetric('rb.matts.parallel.duration_ms', duration);
+    db.logMetric('rb.matts.parallel.success_rate', successRate);
+    db.logMetric('rb.matts.parallel.memories', aggregatedMemories.length);
+    return {
+        runId,
+        mode: 'parallel',
+        k,
+        trajectories,
+        aggregatedMemories,
+        successRate,
+        duration
+    };
+}
+/**
+ * Run MaTTS in sequential mode
+ * Iterative refinement with check-and-correct
+ */
+export async function mattsSequential(taskFn, query, options = {}) {
+    const config = loadConfig();
+    const r = options.r || config.matts.sequential_r || config.matts.sequential_k;
+    const runId = ulid();
+    const startTime = Date.now();
+    console.log(`[INFO] Starting MaTTS sequential mode with r=${r}`);
+    db.storeMattsRun({
+        run_id: runId,
+        task_id: options.taskId || 'matts-seq-' + runId,
+        mode: 'sequential',
+        k: r,
+        status: 'running',
+        summary: undefined
+    });
+    const trajectories = [];
+    let previousMemories = [];
+    // Iterative refinement
+    for (let i = 0; i < r; i++) {
+        console.log(`[INFO] MaTTS sequential iteration ${i + 1}/${r}`);
+        try {
+            // Retrieve relevant memories (including from previous iterations)
+            const memories = await retrieveMemories(query, {
+                domain: options.domain
+            });
+            // Execute with memories
+            const trajectory = await taskFn([...memories, ...previousMemories]);
+            const verdict = await judgeTrajectory(trajectory, query);
+            trajectories.push({
+                id: ulid(),
+                verdict,
+                trajectory
+            });
+            // If success and stop_on_success is true, break early
+            if (verdict.label === 'Success' && (config.matts.sequential_stop_on_success ?? true)) {
+                console.log(`[INFO] Success achieved at iteration ${i + 1}, stopping early`);
+                break;
+            }
+            // Distill memories from this iteration
+            const newMemories = await distillMemories(trajectory, verdict, query, options);
+            previousMemories = [...previousMemories, ...newMemories];
+            // Store trajectory
+            db.storeTrajectory({
+                task_id: options.taskId || 'matts-seq-' + runId,
+                agent_id: options.agentId || 'matts-agent',
+                query,
+                trajectory_json: JSON.stringify(trajectory),
+                started_at: new Date().toISOString(),
+                ended_at: new Date().toISOString(),
+                judge_label: verdict.label,
+                judge_conf: verdict.confidence,
+                judge_reasons: JSON.stringify(verdict.reasons),
+                matts_run_id: runId
+            });
+        }
+        catch (error) {
+            console.error(`[ERROR] MaTTS iteration ${i + 1} failed:`, error);
+        }
+    }
+    const successRate = trajectories.filter(t => t.verdict.label === 'Success').length / trajectories.length;
+    const duration = Date.now() - startTime;
+    console.log(`[INFO] MaTTS sequential complete: ${trajectories.length} iterations, ${successRate * 100}% success in ${duration}ms`);
+    db.logMetric('rb.matts.sequential.duration_ms', duration);
+    db.logMetric('rb.matts.sequential.success_rate', successRate);
+    return {
+        runId,
+        mode: 'sequential',
+        k: r,
+        trajectories,
+        aggregatedMemories: previousMemories,
+        successRate,
+        duration
+    };
+}
+/**
+ * Aggregate memories from multiple trajectories using self-contrast
+ */
+async function aggregateMemories(trajectories, query, options) {
+    console.log('[INFO] Aggregating memories via self-contrast');
+    // Load aggregation prompt
+    const promptPath = join(process.cwd(), 'src', 'reasoningbank', 'prompts', 'matts-aggregate.json');
+    const promptTemplate = JSON.parse(readFileSync(promptPath, 'utf-8'));
+    // Format trajectories for comparison
+    const trajectoryTexts = trajectories.map((t, i) => ({
+        id: t.id,
+        label: t.verdict.label,
+        confidence: t.verdict.confidence,
+        steps: JSON.stringify(t.trajectory.steps || [], null, 2)
+    }));
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        console.warn('[WARN] No API key, skipping aggregation');
+        return [];
+    }
+    try {
+        const prompt = promptTemplate.template
+            .replace('{{k}}', String(trajectories.length))
+            .replace('{{task_query}}', query)
+            .replace('{{trajectories}}', JSON.stringify(trajectoryTexts, null, 2));
+        const response = await fetch('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'x-api-key': apiKey,
+                'anthropic-version': '2023-06-01',
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                model: promptTemplate.model,
+                max_tokens: promptTemplate.max_tokens,
+                temperature: promptTemplate.temperature,
+                system: promptTemplate.system,
+                messages: [{ role: 'user', content: prompt }]
+            })
+        });
+        if (!response.ok) {
+            throw new Error(`Anthropic API error: ${response.status}`);
+        }
+        const result = await response.json();
+        const content = result.content[0].text;
+        // Parse and store aggregated memories
+        const jsonMatch = content.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            const parsed = JSON.parse(jsonMatch[0]);
+            const memories = parsed.memories || [];
+            // Store with boosted confidence
+            const memoryIds = [];
+            for (const mem of memories) {
+                const verdict = { label: 'Success', confidence: 0.9, reasons: [] };
+                const ids = await distillMemories({ steps: [] }, verdict, query, options);
+                memoryIds.push(...ids);
+            }
+            return memoryIds;
+        }
+    }
+    catch (error) {
+        console.error('[ERROR] Memory aggregation failed:', error);
+    }
+    return [];
+}

package/dist/reasoningbank/core/retrieve.js

@@ -0,0 +1,86 @@
+/**
+ * Memory Retrieval with MMR diversity
+ * Algorithm 1 from ReasoningBank paper
+ */
+import { computeEmbedding } from '../utils/embeddings.js';
+import { mmrSelection, cosineSimilarity } from '../utils/mmr.js';
+import * as db from '../db/queries.js';
+import { loadConfig } from '../utils/config.js';
+/**
+ * Retrieve top-k memories with MMR diversity
+ *
+ * Scoring formula: score = α·sim + β·recency + γ·reliability
+ * Where:
+ * - sim: cosine similarity to query
+ * - recency: exp(-age_days / half_life)
+ * - reliability: min(confidence, 1.0)
+ */
+export async function retrieveMemories(query, options = {}) {
+    const config = loadConfig();
+    const k = options.k || config.retrieve.k;
+    const startTime = Date.now();
+    console.log(`[INFO] Retrieving memories for query: ${query.substring(0, 100)}...`);
+    // 1. Embed query
+    const queryEmbed = await computeEmbedding(query);
+    // 2. Fetch candidates from database
+    const candidates = db.fetchMemoryCandidates({
+        domain: options.domain,
+        agent: options.agent,
+        minConfidence: config.retrieve.min_score
+    });
+    if (candidates.length === 0) {
+        console.log('[INFO] No memory candidates found');
+        return [];
+    }
+    console.log(`[INFO] Found ${candidates.length} candidates`);
+    // 3. Score each candidate with 4-factor model
+    const scored = candidates.map(item => {
+        const similarity = cosineSimilarity(queryEmbed, item.embedding);
+        const recency = Math.exp(-item.age_days / config.retrieve.recency_half_life_days);
+        const reliability = Math.min(item.confidence, 1.0);
+        const baseScore = config.retrieve.alpha * similarity +
+            config.retrieve.beta * recency +
+            config.retrieve.gamma * reliability;
+        return {
+            ...item,
+            score: baseScore,
+            components: { similarity, recency, reliability }
+        };
+    });
+    // 4. MMR selection for diversity
+    const selected = mmrSelection(scored, queryEmbed, k, config.retrieve.delta);
+    // 5. Record usage for selected memories
+    for (const mem of selected) {
+        db.incrementUsage(mem.id);
+    }
+    const duration = Date.now() - startTime;
+    console.log(`[INFO] Retrieval complete: ${selected.length} memories in ${duration}ms`);
+    db.logMetric('rb.retrieve.latency_ms', duration);
+    return selected.map(item => ({
+        id: item.id,
+        title: item.pattern_data.title,
+        description: item.pattern_data.description,
+        content: item.pattern_data.content,
+        score: item.score,
+        components: item.components
+    }));
+}
+/**
+ * Format memories for injection into system prompt
+ */
+export function formatMemoriesForPrompt(memories) {
+    if (memories.length === 0) {
+        return '';
+    }
+    let formatted = '\n## Relevant Memories from Past Experience\n\n';
+    for (let i = 0; i < memories.length; i++) {
+        const mem = memories[i];
+        formatted += `### Memory ${i + 1}: ${mem.title}\n\n`;
+        formatted += `${mem.description}\n\n`;
+        formatted += `**Strategy:**\n${mem.content}\n\n`;
+        formatted += `*Confidence: ${(mem.score * 100).toFixed(1)}% | `;
+        formatted += `Similarity: ${(mem.components.similarity * 100).toFixed(1)}%*\n\n`;
+        formatted += '---\n\n';
+    }
+    return formatted;
+}