agentic-flow 2.0.7 → 3.0.0-alpha.2

package/dist/packages/agentdb/src/controllers/ExplainableRecall.d.ts

@@ -0,0 +1,193 @@
+/**
+ * ExplainableRecall - Provenance and Justification for Memory Retrieval
+ *
+ * Every retrieval returns:
+ * - Minimal hitting set of facts that justify the answer
+ * - Merkle proof chain for provenance
+ * - Policy compliance certificates
+ *
+ * Based on:
+ * - Minimal hitting set algorithms
+ * - Merkle tree provenance
+ * - Explainable AI techniques
+ *
+ * v2.0.0-alpha.3 Features:
+ * - GraphRoPE for hop-distance-aware graph queries (WASM)
+ * - Rotary positional encoding based on graph structure
+ * - Feature flag: ENABLE_GRAPH_ROPE (default: false)
+ * - 100% backward compatible with fallback to standard retrieval
+ */
+type Database = any;
+import { type GraphRoPEConfig } from '../utils/LegacyAttentionAdapter.js';
+import { EmbeddingService } from './EmbeddingService.js';
+/**
+ * Configuration for ExplainableRecall
+ */
+export interface ExplainableRecallConfig {
+    /** Enable GraphRoPE for hop-aware queries (default: false) */
+    ENABLE_GRAPH_ROPE?: boolean;
+    /** GraphRoPE configuration */
+    graphRoPEConfig?: Partial<GraphRoPEConfig>;
+}
+export interface RecallCertificate {
+    id: string;
+    queryId: string;
+    queryText: string;
+    chunkIds: string[];
+    chunkTypes: string[];
+    minimalWhy: string[];
+    redundancyRatio: number;
+    completenessScore: number;
+    merkleRoot: string;
+    sourceHashes: string[];
+    proofChain: MerkleProof[];
+    policyProof?: string;
+    policyVersion?: string;
+    accessLevel: 'public' | 'internal' | 'confidential' | 'restricted';
+    latencyMs?: number;
+    metadata?: Record<string, any>;
+}
+export interface MerkleProof {
+    hash: string;
+    position: 'left' | 'right';
+}
+export interface JustificationPath {
+    chunkId: string;
+    chunkType: string;
+    reason: 'semantic_match' | 'causal_link' | 'prerequisite' | 'constraint';
+    necessityScore: number;
+    pathElements: string[];
+}
+export interface ProvenanceSource {
+    id?: number;
+    sourceType: 'episode' | 'skill' | 'note' | 'fact' | 'external';
+    sourceId: number;
+    contentHash: string;
+    parentHash?: string;
+    derivedFrom?: string[];
+    creator?: string;
+    metadata?: Record<string, any>;
+}
+export declare class ExplainableRecall {
+    private db;
+    private attentionService?;
+    private embedder?;
+    private config;
+    /**
+     * Constructor supports both v1 (legacy) and v2 (with GraphRoPE) modes
+     *
+     * v1 mode: new ExplainableRecall(db)
+     * v2 mode: new ExplainableRecall(db, embedder, config)
+     */
+    constructor(db: Database, embedder?: EmbeddingService, config?: ExplainableRecallConfig);
+    /**
+     * Create a recall certificate for a retrieval operation
+     *
+     * v2: Uses GraphRoPE if enabled for hop-distance-aware justification scoring
+     * v1: Falls back to standard relevance-based justification
+     */
+    createCertificate(params: {
+        queryId: string;
+        queryText: string;
+        chunks: Array<{
+            id: string;
+            type: string;
+            content: string;
+            relevance: number;
+        }>;
+        requirements: string[];
+        accessLevel?: string;
+        hopDistances?: number[][];
+    }): Promise<RecallCertificate>;
+    /**
+     * Verify a recall certificate
+     */
+    verifyCertificate(certificateId: string): {
+        valid: boolean;
+        issues: string[];
+    };
+    /**
+     * Get justification for why a chunk was included
+     */
+    getJustification(certificateId: string, chunkId: string): JustificationPath | null;
+    /**
+     * Get provenance lineage for a source
+     */
+    getProvenanceLineage(contentHash: string): ProvenanceSource[];
+    /**
+     * Trace provenance lineage for a certificate
+     * Returns full provenance chain from certificate to original sources
+     */
+    traceProvenance(certificateId: string): {
+        certificate: RecallCertificate;
+        sources: Map<string, ProvenanceSource[]>;
+        graph: {
+            nodes: Array<{
+                id: string;
+                type: string;
+                label: string;
+            }>;
+            edges: Array<{
+                from: string;
+                to: string;
+                type: string;
+            }>;
+        };
+    };
+    /**
+     * Audit certificate access
+     */
+    auditCertificate(certificateId: string): {
+        certificate: RecallCertificate;
+        justifications: JustificationPath[];
+        provenance: Map<string, ProvenanceSource[]>;
+        quality: {
+            completeness: number;
+            redundancy: number;
+            avgNecessity: number;
+        };
+    };
+    /**
+     * Compute minimal hitting set using greedy algorithm
+     * A hitting set contains at least one element from each requirement
+     */
+    private computeMinimalHittingSet;
+    /**
+     * Calculate completeness score
+     */
+    private calculateCompleteness;
+    /**
+     * Get or create provenance record
+     */
+    private getOrCreateProvenance;
+    private _episodeStmt?;
+    private _skillStmt?;
+    private _noteStmt?;
+    private _factStmt?;
+    /**
+     * Get content hash for a memory
+     */
+    private getContentHash;
+    /**
+     * Build Merkle tree from hashes
+     */
+    private buildMerkleTree;
+    /**
+     * Get Merkle proof for a leaf
+     */
+    private getMerkleProof;
+    /**
+     * Generate certificate ID
+     */
+    private generateCertificateId;
+    /**
+     * Store justification paths
+     */
+    private storeJustificationPaths;
+    /**
+     * Determine reason for inclusion
+     */
+    private determineReason;
+}
+export {};
+//# sourceMappingURL=ExplainableRecall.d.ts.map

package/dist/packages/agentdb/src/controllers/ExplainableRecall.d.ts.map

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