agentdb 1.6.1 → 2.0.0-alpha.2

package/dist/src/controllers/CausalMemoryGraph.d.ts

@@ -0,0 +1,127 @@
+/**
+ * CausalMemoryGraph - Causal Reasoning over Agent Memories
+ *
+ * Implements intervention-based reasoning rather than correlation.
+ * Stores p(y|do(x)) estimates and tracks causal uplift across episodes.
+ *
+ * Based on:
+ * - Pearl's do-calculus and causal inference
+ * - Uplift modeling from A/B testing
+ * - Instrumental variable methods
+ */
+type Database = any;
+export interface CausalEdge {
+    id?: number;
+    fromMemoryId: number;
+    fromMemoryType: 'episode' | 'skill' | 'note' | 'fact';
+    toMemoryId: number;
+    toMemoryType: 'episode' | 'skill' | 'note' | 'fact';
+    similarity: number;
+    uplift?: number;
+    confidence: number;
+    sampleSize?: number;
+    evidenceIds?: string[];
+    experimentIds?: string[];
+    confounderScore?: number;
+    mechanism?: string;
+    metadata?: Record<string, any>;
+}
+export interface CausalExperiment {
+    id?: number;
+    name: string;
+    hypothesis: string;
+    treatmentId: number;
+    treatmentType: string;
+    controlId?: number;
+    startTime: number;
+    endTime?: number;
+    sampleSize: number;
+    treatmentMean?: number;
+    controlMean?: number;
+    uplift?: number;
+    pValue?: number;
+    confidenceIntervalLow?: number;
+    confidenceIntervalHigh?: number;
+    status: 'running' | 'completed' | 'failed';
+    metadata?: Record<string, any>;
+}
+export interface CausalObservation {
+    experimentId: number;
+    episodeId: number;
+    isTreatment: boolean;
+    outcomeValue: number;
+    outcomeType: 'reward' | 'success' | 'latency';
+    context?: Record<string, any>;
+}
+export interface CausalQuery {
+    interventionMemoryId: number;
+    interventionMemoryType: string;
+    outcomeMemoryId?: number;
+    minConfidence?: number;
+    minUplift?: number;
+}
+export declare class CausalMemoryGraph {
+    private db;
+    private graphBackend?;
+    constructor(db: Database, graphBackend?: any);
+    /**
+     * Add a causal edge between memories
+     */
+    addCausalEdge(edge: CausalEdge): Promise<number>;
+    /**
+     * Create a causal experiment (A/B test)
+     */
+    createExperiment(experiment: CausalExperiment): number;
+    /**
+     * Record an observation in an experiment
+     */
+    recordObservation(observation: CausalObservation): void;
+    /**
+     * Calculate uplift for an experiment
+     */
+    calculateUplift(experimentId: number): {
+        uplift: number;
+        pValue: number;
+        confidenceInterval: [number, number];
+    };
+    /**
+     * Query causal effects
+     */
+    queryCausalEffects(query: CausalQuery): CausalEdge[];
+    /**
+     * Get causal chain (multi-hop reasoning)
+     */
+    getCausalChain(fromMemoryId: number, toMemoryId: number, maxDepth?: number): {
+        path: number[];
+        totalUplift: number;
+        confidence: number;
+    }[];
+    /**
+     * Calculate causal gain: E[outcome|do(treatment)] - E[outcome]
+     */
+    calculateCausalGain(treatmentId: number, outcomeType: 'reward' | 'success' | 'latency'): {
+        causalGain: number;
+        confidence: number;
+        mechanism: string;
+    };
+    /**
+     * Detect confounders using correlation analysis
+     */
+    detectConfounders(edgeId: number): {
+        confounders: Array<{
+            memoryId: number;
+            correlationWithTreatment: number;
+            correlationWithOutcome: number;
+            confounderScore: number;
+        }>;
+    };
+    private rowToCausalEdge;
+    private mean;
+    private variance;
+    private standardError;
+    private tCDF;
+    private tInverse;
+    private calculateCorrelation;
+}
+export {};
+//# sourceMappingURL=CausalMemoryGraph.d.ts.map

package/dist/src/controllers/CausalMemoryGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CausalMemoryGraph.d.ts","sourceRoot":"","sources":["../../../src/controllers/CausalMemoryGraph.ts"],"names":[],"mappings":"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"}

package/dist/src/controllers/CausalMemoryGraph.js

@@ -0,0 +1,354 @@
+/**
+ * CausalMemoryGraph - Causal Reasoning over Agent Memories
+ *
+ * Implements intervention-based reasoning rather than correlation.
+ * Stores p(y|do(x)) estimates and tracks causal uplift across episodes.
+ *
+ * Based on:
+ * - Pearl's do-calculus and causal inference
+ * - Uplift modeling from A/B testing
+ * - Instrumental variable methods
+ */
+import { NodeIdMapper } from '../utils/NodeIdMapper.js';
+export class CausalMemoryGraph {
+    db;
+    graphBackend; // GraphBackend or GraphDatabaseAdapter
+    constructor(db, graphBackend) {
+        this.db = db;
+        this.graphBackend = graphBackend;
+    }
+    /**
+     * Add a causal edge between memories
+     */
+    async addCausalEdge(edge) {
+        // Use GraphDatabaseAdapter if available (AgentDB v2)
+        if (this.graphBackend && 'createCausalEdge' in this.graphBackend) {
+            const graphAdapter = this.graphBackend;
+            // Create embedding for causal mechanism
+            const mechanismText = edge.mechanism || `${edge.fromMemoryType}-${edge.toMemoryType} causal link`;
+            const embedding = new Float32Array(384).fill(0); // Placeholder - would use embedder in production
+            // Convert episode IDs to string format expected by graph database
+            // Use NodeIdMapper to get full node IDs from numeric IDs
+            const mapper = NodeIdMapper.getInstance();
+            const fromNodeId = typeof edge.fromMemoryId === 'string'
+                ? edge.fromMemoryId
+                : (mapper.getNodeId(edge.fromMemoryId) || `${edge.fromMemoryType}-${edge.fromMemoryId}`);
+            const toNodeId = typeof edge.toMemoryId === 'string'
+                ? edge.toMemoryId
+                : (mapper.getNodeId(edge.toMemoryId) || `${edge.toMemoryType}-${edge.toMemoryId}`);
+            const graphEdge = {
+                from: fromNodeId,
+                to: toNodeId,
+                mechanism: mechanismText,
+                uplift: edge.uplift || 0,
+                confidence: edge.confidence,
+                sampleSize: edge.sampleSize || 0
+            };
+            const edgeId = await graphAdapter.createCausalEdge(graphEdge, embedding);
+            // Return a numeric ID for compatibility
+            return edge.fromMemoryId;
+        }
+        // Fallback to SQLite
+        const stmt = this.db.prepare(`
+      INSERT INTO causal_edges (
+        from_memory_id, from_memory_type, to_memory_id, to_memory_type,
+        similarity, uplift, confidence, sample_size,
+        evidence_ids, confounder_score,
+        mechanism, metadata
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const result = stmt.run(edge.fromMemoryId, edge.fromMemoryType, edge.toMemoryId, edge.toMemoryType, edge.similarity, edge.uplift || null, edge.confidence, edge.sampleSize || null, edge.evidenceIds ? JSON.stringify(edge.evidenceIds) : null, edge.confounderScore || null, edge.mechanism || null, edge.metadata ? JSON.stringify(edge.metadata) : null);
+        return result.lastInsertRowid;
+    }
+    /**
+     * Create a causal experiment (A/B test)
+     */
+    createExperiment(experiment) {
+        const stmt = this.db.prepare(`
+      INSERT INTO causal_experiments (
+        name, hypothesis, treatment_id, treatment_type, control_id,
+        start_time, sample_size, status, metadata
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const result = stmt.run(experiment.name, experiment.hypothesis, experiment.treatmentId, experiment.treatmentType, experiment.controlId || null, experiment.startTime, experiment.sampleSize, experiment.status, experiment.metadata ? JSON.stringify(experiment.metadata) : null);
+        return result.lastInsertRowid;
+    }
+    /**
+     * Record an observation in an experiment
+     */
+    recordObservation(observation) {
+        const stmt = this.db.prepare(`
+      INSERT INTO causal_observations (
+        experiment_id, episode_id, is_treatment, outcome_value, outcome_type, context
+      ) VALUES (?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(observation.experimentId, observation.episodeId, observation.isTreatment ? 1 : 0, observation.outcomeValue, observation.outcomeType, observation.context ? JSON.stringify(observation.context) : null);
+        // Update sample size
+        this.db.prepare(`
+      UPDATE causal_experiments
+      SET sample_size = sample_size + 1
+      WHERE id = ?
+    `).run(observation.experimentId);
+    }
+    /**
+     * Calculate uplift for an experiment
+     */
+    calculateUplift(experimentId) {
+        // Get treatment and control observations
+        const observations = this.db.prepare(`
+      SELECT is_treatment, outcome_value
+      FROM causal_observations
+      WHERE experiment_id = ?
+    `).all(experimentId);
+        const treatmentValues = observations
+            .filter(o => o.is_treatment === 1)
+            .map(o => o.outcome_value);
+        const controlValues = observations
+            .filter(o => o.is_treatment === 0)
+            .map(o => o.outcome_value);
+        if (treatmentValues.length === 0 || controlValues.length === 0) {
+            return { uplift: 0, pValue: 1.0, confidenceInterval: [0, 0] };
+        }
+        // Calculate means
+        const treatmentMean = this.mean(treatmentValues);
+        const controlMean = this.mean(controlValues);
+        const uplift = treatmentMean - controlMean;
+        // Calculate standard errors
+        const treatmentSE = this.standardError(treatmentValues);
+        const controlSE = this.standardError(controlValues);
+        const pooledSE = Math.sqrt(treatmentSE ** 2 + controlSE ** 2);
+        // t-statistic and p-value (two-tailed)
+        const tStat = uplift / pooledSE;
+        const df = treatmentValues.length + controlValues.length - 2;
+        const pValue = 2 * (1 - this.tCDF(Math.abs(tStat), df));
+        // 95% confidence interval
+        const tCritical = this.tInverse(0.025, df);
+        const marginOfError = tCritical * pooledSE;
+        const confidenceInterval = [
+            uplift - marginOfError,
+            uplift + marginOfError
+        ];
+        // Update experiment with results
+        this.db.prepare(`
+      UPDATE causal_experiments
+      SET treatment_mean = ?,
+          control_mean = ?,
+          uplift = ?,
+          p_value = ?,
+          confidence_interval_low = ?,
+          confidence_interval_high = ?,
+          status = 'completed'
+      WHERE id = ?
+    `).run(treatmentMean, controlMean, uplift, pValue, confidenceInterval[0], confidenceInterval[1], experimentId);
+        return { uplift, pValue, confidenceInterval };
+    }
+    /**
+     * Query causal effects
+     */
+    queryCausalEffects(query) {
+        const { interventionMemoryId, interventionMemoryType, outcomeMemoryId, minConfidence = 0.5, minUplift = 0.0 } = query;
+        let sql = `
+      SELECT * FROM causal_edges
+      WHERE from_memory_id = ?
+        AND from_memory_type = ?
+        AND confidence >= ?
+        AND ABS(uplift) >= ?
+    `;
+        const params = [
+            interventionMemoryId,
+            interventionMemoryType,
+            minConfidence,
+            minUplift
+        ];
+        if (outcomeMemoryId) {
+            sql += ' AND to_memory_id = ?';
+            params.push(outcomeMemoryId);
+        }
+        sql += ' ORDER BY ABS(uplift) * confidence DESC';
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(row => this.rowToCausalEdge(row));
+    }
+    /**
+     * Get causal chain (multi-hop reasoning)
+     */
+    getCausalChain(fromMemoryId, toMemoryId, maxDepth = 5) {
+        // Use recursive CTE from view
+        const chains = this.db.prepare(`
+      WITH RECURSIVE chain(from_id, to_id, depth, path, total_uplift, min_confidence) AS (
+        SELECT
+          from_memory_id,
+          to_memory_id,
+          1,
+          from_memory_id || '->' || to_memory_id,
+          uplift,
+          confidence
+        FROM causal_edges
+        WHERE from_memory_id = ? AND confidence >= 0.5
+
+        UNION ALL
+
+        SELECT
+          chain.from_id,
+          ce.to_memory_id,
+          chain.depth + 1,
+          chain.path || '->' || ce.to_memory_id,
+          chain.total_uplift + ce.uplift,
+          MIN(chain.min_confidence, ce.confidence)
+        FROM chain
+        JOIN causal_edges ce ON chain.to_id = ce.from_memory_id
+        WHERE chain.depth < ?
+          AND ce.confidence >= 0.5
+          AND chain.path NOT LIKE '%' || ce.to_memory_id || '%'
+      )
+      SELECT path, total_uplift, min_confidence
+      FROM chain
+      WHERE to_id = ?
+      ORDER BY total_uplift DESC
+      LIMIT 10
+    `).all(fromMemoryId, maxDepth, toMemoryId);
+        return chains.map(row => ({
+            path: row.path.split('->').map(Number),
+            totalUplift: row.total_uplift,
+            confidence: row.min_confidence
+        }));
+    }
+    /**
+     * Calculate causal gain: E[outcome|do(treatment)] - E[outcome]
+     */
+    calculateCausalGain(treatmentId, outcomeType) {
+        // Get episodes where treatment was applied
+        const withTreatment = this.db.prepare(`
+      SELECT AVG(CASE WHEN ? = 'reward' THEN reward
+                     WHEN ? = 'success' THEN success
+                     WHEN ? = 'latency' THEN latency_ms
+                END) as avg_outcome
+      FROM episodes
+      WHERE id IN (
+        SELECT to_memory_id FROM causal_edges
+        WHERE from_memory_id = ? AND confidence >= 0.6
+      )
+    `).get(outcomeType, outcomeType, outcomeType, treatmentId);
+        // Get baseline (no treatment)
+        const baseline = this.db.prepare(`
+      SELECT AVG(CASE WHEN ? = 'reward' THEN reward
+                     WHEN ? = 'success' THEN success
+                     WHEN ? = 'latency' THEN latency_ms
+                END) as avg_outcome
+      FROM episodes
+      WHERE id NOT IN (
+        SELECT to_memory_id FROM causal_edges
+        WHERE from_memory_id = ?
+      )
+    `).get(outcomeType, outcomeType, outcomeType, treatmentId);
+        const causalGain = (withTreatment?.avg_outcome || 0) - (baseline?.avg_outcome || 0);
+        // Get most confident edge for mechanism
+        const edge = this.db.prepare(`
+      SELECT mechanism, confidence
+      FROM causal_edges
+      WHERE from_memory_id = ?
+      ORDER BY confidence DESC
+      LIMIT 1
+    `).get(treatmentId);
+        return {
+            causalGain,
+            confidence: edge?.confidence || 0,
+            mechanism: edge?.mechanism || 'unknown'
+        };
+    }
+    /**
+     * Detect confounders using correlation analysis
+     */
+    detectConfounders(edgeId) {
+        const edge = this.db.prepare('SELECT * FROM causal_edges WHERE id = ?').get(edgeId);
+        if (!edge) {
+            return { confounders: [] };
+        }
+        // Find memories correlated with both treatment and outcome
+        // This is a simplified version - production would use proper statistical tests
+        const potentialConfounders = this.db.prepare(`
+      SELECT DISTINCT e.id, e.task
+      FROM episodes e
+      WHERE e.id != ? AND e.id != ?
+        AND e.session_id IN (
+          SELECT session_id FROM episodes WHERE id = ?
+          UNION
+          SELECT session_id FROM episodes WHERE id = ?
+        )
+    `).all(edge.from_memory_id, edge.to_memory_id, edge.from_memory_id, edge.to_memory_id);
+        const confounders = potentialConfounders.map((conf) => {
+            // Calculate correlation scores (simplified)
+            const treatmentCorr = this.calculateCorrelation(conf.id, edge.from_memory_id);
+            const outcomeCorr = this.calculateCorrelation(conf.id, edge.to_memory_id);
+            const confounderScore = Math.sqrt(treatmentCorr ** 2 * outcomeCorr ** 2);
+            return {
+                memoryId: conf.id,
+                correlationWithTreatment: treatmentCorr,
+                correlationWithOutcome: outcomeCorr,
+                confounderScore
+            };
+        }).filter(c => c.confounderScore > 0.3);
+        // Update edge with confounder score
+        if (confounders.length > 0) {
+            const maxConfounderScore = Math.max(...confounders.map(c => c.confounderScore));
+            this.db.prepare(`
+        UPDATE causal_edges
+        SET confounder_score = ?
+        WHERE id = ?
+      `).run(maxConfounderScore, edgeId);
+        }
+        return { confounders };
+    }
+    // ========================================================================
+    // Private Helper Methods
+    // ========================================================================
+    rowToCausalEdge(row) {
+        return {
+            id: row.id,
+            fromMemoryId: row.from_memory_id,
+            fromMemoryType: row.from_memory_type,
+            toMemoryId: row.to_memory_id,
+            toMemoryType: row.to_memory_type,
+            similarity: row.similarity,
+            uplift: row.uplift,
+            confidence: row.confidence,
+            sampleSize: row.sample_size,
+            evidenceIds: row.evidence_ids ? JSON.parse(row.evidence_ids) : undefined,
+            experimentIds: row.experiment_ids ? JSON.parse(row.experiment_ids) : undefined,
+            confounderScore: row.confounder_score,
+            mechanism: row.mechanism,
+            metadata: row.metadata ? JSON.parse(row.metadata) : undefined
+        };
+    }
+    mean(values) {
+        return values.reduce((a, b) => a + b, 0) / values.length;
+    }
+    variance(values) {
+        const avg = this.mean(values);
+        return values.reduce((sum, val) => sum + (val - avg) ** 2, 0) / values.length;
+    }
+    standardError(values) {
+        return Math.sqrt(this.variance(values) / values.length);
+    }
+    tCDF(t, df) {
+        // Simplified t-distribution CDF (use proper stats library in production)
+        // This is an approximation
+        return 0.5 + 0.5 * Math.sign(t) * (1 - Math.pow(1 + t * t / df, -df / 2));
+    }
+    tInverse(p, df) {
+        // Simplified inverse t-distribution (use proper stats library)
+        // Approximation for 95% CI
+        return 1.96; // Standard normal approximation
+    }
+    calculateCorrelation(id1, id2) {
+        // Simplified correlation calculation
+        // In production, use proper correlation metrics
+        const sharedSessions = this.db.prepare(`
+      SELECT COUNT(DISTINCT e1.session_id) as shared
+      FROM episodes e1
+      JOIN episodes e2 ON e1.session_id = e2.session_id
+      WHERE e1.id = ? AND e2.id = ?
+    `).get(id1, id2);
+        return Math.min(sharedSessions?.shared || 0, 1.0);
+    }
+}
+//# sourceMappingURL=CausalMemoryGraph.js.map

package/dist/src/controllers/CausalMemoryGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CausalMemoryGraph.js","sourceRoot":"","sources":["../../../src/controllers/CausalMemoryGraph.ts"],"names":[],"mappings":"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"}

package/dist/src/controllers/CausalRecall.d.ts

@@ -0,0 +1,139 @@
+/**
+ * CausalRecall - Utility-Based Reranking + Certificate Issuer
+ *
+ * Combines:
+ * 1. Vector similarity search
+ * 2. Causal uplift from CausalMemoryGraph
+ * 3. Utility-based reranking: U = α*similarity + β*uplift − γ*latencyCost
+ * 4. Automatic certificate issuance via ExplainableRecall
+ *
+ * This is the main entry point for production retrieval with:
+ * - Causal-aware ranking
+ * - Explainable provenance
+ * - Policy compliance
+ */
+type Database = any;
+import { RecallCertificate } from './ExplainableRecall.js';
+import { EmbeddingService } from './EmbeddingService.js';
+import type { VectorBackend } from '../backends/VectorBackend.js';
+export interface RerankConfig {
+    alpha: number;
+    beta: number;
+    gamma: number;
+    minConfidence?: number;
+}
+export interface RerankCandidate {
+    id: string;
+    type: 'episode' | 'skill' | 'note' | 'fact';
+    content: string;
+    similarity: number;
+    uplift?: number;
+    causalConfidence?: number;
+    latencyMs?: number;
+    utilityScore: number;
+    rank: number;
+}
+export interface CausalRecallResult {
+    candidates: RerankCandidate[];
+    certificate: RecallCertificate;
+    queryId: string;
+    totalLatencyMs: number;
+    metrics: {
+        vectorSearchMs: number;
+        causalLookupMs: number;
+        rerankMs: number;
+        certificateMs: number;
+    };
+}
+export declare class CausalRecall {
+    private config;
+    private db;
+    private causalGraph;
+    private explainableRecall;
+    private embedder;
+    private vectorBackend?;
+    constructor(db: Database, embedder: EmbeddingService, vectorBackend?: VectorBackend, config?: RerankConfig);
+    /**
+     * Main recall function with utility-based reranking and certificate issuance
+     *
+     * @param queryId Unique query identifier
+     * @param queryText Natural language query
+     * @param k Number of results to return (default: 12)
+     * @param requirements Optional list of requirements for completeness checking
+     * @param accessLevel Security access level for certificate
+     * @returns Reranked results with certificate
+     */
+    recall(queryId: string, queryText: string, k?: number, requirements?: string[], accessLevel?: 'public' | 'internal' | 'confidential' | 'restricted'): Promise<CausalRecallResult>;
+    /**
+     * Vector similarity search using cosine similarity
+     */
+    private vectorSearch;
+    /**
+     * Load causal edges for candidates
+     */
+    private loadCausalEdges;
+    /**
+     * Rerank by utility: U = α*similarity + β*uplift − γ*latencyCost
+     */
+    private rerankByUtility;
+    /**
+     * Issue certificate for the retrieval
+     */
+    private issueCertificate;
+    /**
+     * Extract requirements from query text (simple keyword extraction)
+     */
+    private extractRequirements;
+    /**
+     * Deserialize embedding from Buffer
+     */
+    private deserializeEmbedding;
+    /**
+     * Cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+    /**
+     * Batch recall for multiple queries
+     */
+    batchRecall(queries: Array<{
+        queryId: string;
+        queryText: string;
+        k?: number;
+    }>, requirements?: string[], accessLevel?: 'public' | 'internal' | 'confidential' | 'restricted'): Promise<CausalRecallResult[]>;
+    /**
+     * Get recall statistics
+     */
+    getStats(): {
+        totalCausalEdges: number;
+        totalCertificates: number;
+        avgRedundancyRatio: number;
+        avgCompletenessScore: number;
+    };
+    /**
+     * Update rerank configuration
+     */
+    updateConfig(config: Partial<RerankConfig>): void;
+    /**
+     * Search for memories with semantic similarity and causal utility ranking
+     *
+     * @param params Search parameters
+     * @returns Array of ranked search results with similarity and causal uplift scores
+     */
+    search(params: {
+        query: string;
+        k?: number;
+        includeEvidence?: boolean;
+        alpha?: number;
+        beta?: number;
+        gamma?: number;
+    }): Promise<Array<{
+        id: number;
+        type: string;
+        content: string;
+        similarity: number;
+        causalUplift: number;
+        utilityScore: number;
+    }>>;
+}
+export {};
+//# sourceMappingURL=CausalRecall.d.ts.map

package/dist/src/controllers/CausalRecall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CausalRecall.d.ts","sourceRoot":"","sources":["../../../src/controllers/CausalRecall.ts"],"names":[],"mappings":"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"}