agentdb 1.6.0 → 2.0.0-alpha.1

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

@@ -0,0 +1,37 @@
+/**
+ * EmbeddingService - Text Embedding Generation
+ *
+ * Handles text-to-vector embedding generation using various models.
+ * Supports both local (transformers.js) and remote (OpenAI, etc.) embeddings.
+ */
+export interface EmbeddingConfig {
+    model: string;
+    dimension: number;
+    provider: 'transformers' | 'openai' | 'local';
+    apiKey?: string;
+}
+export declare class EmbeddingService {
+    private config;
+    private pipeline;
+    private cache;
+    constructor(config: EmbeddingConfig);
+    /**
+     * Initialize the embedding service
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate embedding for text
+     */
+    embed(text: string): Promise<Float32Array>;
+    /**
+     * Batch embed multiple texts
+     */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    /**
+     * Clear embedding cache
+     */
+    clearCache(): void;
+    private embedOpenAI;
+    private mockEmbedding;
+}
+//# sourceMappingURL=EmbeddingService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddingService.d.ts","sourceRoot":"","sources":["../../../src/controllers/EmbeddingService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,KAAK,CAA4B;gBAE7B,MAAM,EAAE,eAAe;IAKnC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BjC;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgChD;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAI1D;;OAEG;IACH,UAAU,IAAI,IAAI;YAQJ,WAAW;IAiBzB,OAAO,CAAC,aAAa;CAmCtB"}

package/dist/src/controllers/EmbeddingService.js

@@ -0,0 +1,136 @@
+/**
+ * EmbeddingService - Text Embedding Generation
+ *
+ * Handles text-to-vector embedding generation using various models.
+ * Supports both local (transformers.js) and remote (OpenAI, etc.) embeddings.
+ */
+export class EmbeddingService {
+    config;
+    pipeline; // transformers.js pipeline
+    cache;
+    constructor(config) {
+        this.config = config;
+        this.cache = new Map();
+    }
+    /**
+     * Initialize the embedding service
+     */
+    async initialize() {
+        if (this.config.provider === 'transformers') {
+            // Use transformers.js for local embeddings
+            try {
+                const transformers = await import('@xenova/transformers');
+                // Set Hugging Face token if available from environment
+                const hfToken = process.env.HUGGINGFACE_API_KEY || process.env.HF_TOKEN;
+                if (hfToken) {
+                    // Set the token for Transformers.js to use
+                    if (transformers.env && typeof transformers.env === 'object') {
+                        transformers.env.HF_TOKEN = hfToken;
+                        console.log('🔑 Using Hugging Face API key from environment');
+                    }
+                }
+                this.pipeline = await transformers.pipeline('feature-extraction', this.config.model);
+                console.log(`✅ Transformers.js loaded: ${this.config.model}`);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.warn(`⚠️  Transformers.js initialization failed: ${errorMessage}`);
+                console.warn('   Falling back to mock embeddings for testing');
+                console.warn('   Set HUGGINGFACE_API_KEY environment variable for real embeddings');
+                this.pipeline = null;
+            }
+        }
+    }
+    /**
+     * Generate embedding for text
+     */
+    async embed(text) {
+        // Check cache
+        const cacheKey = `${this.config.model}:${text}`;
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey);
+        }
+        let embedding;
+        if (this.config.provider === 'transformers' && this.pipeline) {
+            // Use transformers.js
+            const output = await this.pipeline(text, { pooling: 'mean', normalize: true });
+            embedding = new Float32Array(output.data);
+        }
+        else if (this.config.provider === 'openai' && this.config.apiKey) {
+            // Use OpenAI API
+            embedding = await this.embedOpenAI(text);
+        }
+        else {
+            // Mock embedding for testing
+            embedding = this.mockEmbedding(text);
+        }
+        // Cache result
+        if (this.cache.size > 10000) {
+            // Simple LRU: clear half the cache
+            const keysToDelete = Array.from(this.cache.keys()).slice(0, 5000);
+            keysToDelete.forEach(k => this.cache.delete(k));
+        }
+        this.cache.set(cacheKey, embedding);
+        return embedding;
+    }
+    /**
+     * Batch embed multiple texts
+     */
+    async embedBatch(texts) {
+        return Promise.all(texts.map(text => this.embed(text)));
+    }
+    /**
+     * Clear embedding cache
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    // ========================================================================
+    // Private Methods
+    // ========================================================================
+    async embedOpenAI(text) {
+        const response = await fetch('https://api.openai.com/v1/embeddings', {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.config.apiKey}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                model: this.config.model,
+                input: text
+            })
+        });
+        const data = await response.json();
+        return new Float32Array(data.data[0].embedding);
+    }
+    mockEmbedding(text) {
+        // Simple deterministic mock embedding for testing
+        const embedding = new Float32Array(this.config.dimension);
+        // Handle null/undefined/empty text
+        if (!text || text.length === 0) {
+            return new Array(this.config.dimension).fill(0);
+        }
+        // Use simple hash-based generation
+        let hash = 0;
+        for (let i = 0; i < text.length; i++) {
+            hash = ((hash << 5) - hash) + text.charCodeAt(i);
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        // Fill embedding with pseudo-random values based on hash
+        for (let i = 0; i < this.config.dimension; i++) {
+            const seed = hash + i * 31;
+            embedding[i] = Math.sin(seed) * Math.cos(seed * 0.5);
+        }
+        // Normalize
+        let norm = 0;
+        for (let i = 0; i < embedding.length; i++) {
+            norm += embedding[i] * embedding[i];
+        }
+        norm = Math.sqrt(norm);
+        for (let i = 0; i < embedding.length; i++) {
+            embedding[i] /= norm;
+        }
+        return embedding;
+    }
+}
+//# sourceMappingURL=EmbeddingService.js.map

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

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

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

@@ -0,0 +1,50 @@
+/**
+ * Enhanced EmbeddingService with WASM Acceleration
+ *
+ * Extends the base EmbeddingService with WASM-accelerated batch operations
+ * and improved performance for large-scale embedding generation.
+ */
+import { EmbeddingService, EmbeddingConfig } from './EmbeddingService.js';
+export interface EnhancedEmbeddingConfig extends EmbeddingConfig {
+    enableWASM?: boolean;
+    enableBatchProcessing?: boolean;
+    batchSize?: number;
+}
+export declare class EnhancedEmbeddingService extends EmbeddingService {
+    private wasmSearch;
+    private enhancedConfig;
+    constructor(config: EnhancedEmbeddingConfig);
+    /**
+     * Initialize WASM acceleration
+     */
+    private initializeWASM;
+    /**
+     * Enhanced batch embedding with parallel processing
+     */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    /**
+     * Calculate similarity between two texts using WASM acceleration
+     */
+    similarity(textA: string, textB: string): Promise<number>;
+    /**
+     * Find most similar texts from a corpus
+     */
+    findMostSimilar(query: string, corpus: string[], k?: number): Promise<Array<{
+        text: string;
+        similarity: number;
+        index: number;
+    }>>;
+    /**
+     * Get service statistics
+     */
+    getStats(): {
+        cacheSize: number;
+        wasmEnabled: boolean;
+        simdEnabled: boolean;
+    };
+    /**
+     * Cosine similarity fallback
+     */
+    private cosineSimilarity;
+}
+//# sourceMappingURL=EnhancedEmbeddingService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnhancedEmbeddingService.d.ts","sourceRoot":"","sources":["../../../src/controllers/EnhancedEmbeddingService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG1E,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,wBAAyB,SAAQ,gBAAgB;IAC5D,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,cAAc,CAA0B;gBAEpC,MAAM,EAAE,uBAAuB;IAc3C;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAsB1D;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAc/D;;OAEG;IACG,eAAe,CACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EAAE,EAChB,CAAC,GAAE,MAAU,GACZ,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IA0BtE;;OAEG;IACH,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,OAAO,CAAC;QACrB,WAAW,EAAE,OAAO,CAAC;KACtB;IAUD;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAczB"}

package/dist/src/controllers/EnhancedEmbeddingService.js

@@ -0,0 +1,119 @@
+/**
+ * Enhanced EmbeddingService with WASM Acceleration
+ *
+ * Extends the base EmbeddingService with WASM-accelerated batch operations
+ * and improved performance for large-scale embedding generation.
+ */
+import { EmbeddingService } from './EmbeddingService.js';
+import { WASMVectorSearch } from './WASMVectorSearch.js';
+export class EnhancedEmbeddingService extends EmbeddingService {
+    wasmSearch = null;
+    enhancedConfig;
+    constructor(config) {
+        super(config);
+        this.enhancedConfig = {
+            enableWASM: true,
+            enableBatchProcessing: true,
+            batchSize: 100,
+            ...config,
+        };
+        if (this.enhancedConfig.enableWASM) {
+            this.initializeWASM();
+        }
+    }
+    /**
+     * Initialize WASM acceleration
+     */
+    initializeWASM() {
+        const mockDb = {
+            prepare: () => ({ all: () => [], get: () => null, run: () => ({}) }),
+            exec: () => { },
+        };
+        this.wasmSearch = new WASMVectorSearch(mockDb, {
+            enableWASM: true,
+            batchSize: this.enhancedConfig.batchSize || 100,
+        });
+    }
+    /**
+     * Enhanced batch embedding with parallel processing
+     */
+    async embedBatch(texts) {
+        if (!this.enhancedConfig.enableBatchProcessing || texts.length < 10) {
+            return super.embedBatch(texts);
+        }
+        const batchSize = this.enhancedConfig.batchSize || 100;
+        const batches = [];
+        // Split into batches
+        for (let i = 0; i < texts.length; i += batchSize) {
+            batches.push(texts.slice(i, i + batchSize));
+        }
+        // Process batches in parallel
+        const results = await Promise.all(batches.map(batch => super.embedBatch(batch)));
+        // Flatten results
+        return results.flat();
+    }
+    /**
+     * Calculate similarity between two texts using WASM acceleration
+     */
+    async similarity(textA, textB) {
+        const [embeddingA, embeddingB] = await Promise.all([
+            this.embed(textA),
+            this.embed(textB),
+        ]);
+        if (this.wasmSearch) {
+            return this.wasmSearch.cosineSimilarity(embeddingA, embeddingB);
+        }
+        // Fallback to manual calculation
+        return this.cosineSimilarity(embeddingA, embeddingB);
+    }
+    /**
+     * Find most similar texts from a corpus
+     */
+    async findMostSimilar(query, corpus, k = 5) {
+        const queryEmbedding = await this.embed(query);
+        const corpusEmbeddings = await this.embedBatch(corpus);
+        let similarities;
+        if (this.wasmSearch) {
+            similarities = this.wasmSearch.batchSimilarity(queryEmbedding, corpusEmbeddings);
+        }
+        else {
+            similarities = corpusEmbeddings.map(emb => this.cosineSimilarity(queryEmbedding, emb));
+        }
+        // Create results with indices
+        const results = corpus.map((text, index) => ({
+            text,
+            similarity: similarities[index],
+            index,
+        }));
+        // Sort by similarity and take top k
+        results.sort((a, b) => b.similarity - a.similarity);
+        return results.slice(0, k);
+    }
+    /**
+     * Get service statistics
+     */
+    getStats() {
+        const wasmStats = this.wasmSearch?.getStats();
+        return {
+            cacheSize: this.cache.size,
+            wasmEnabled: wasmStats?.wasmAvailable ?? false,
+            simdEnabled: wasmStats?.simdAvailable ?? false,
+        };
+    }
+    /**
+     * Cosine similarity fallback
+     */
+    cosineSimilarity(a, b) {
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denom = Math.sqrt(normA) * Math.sqrt(normB);
+        return denom === 0 ? 0 : dotProduct / denom;
+    }
+}
+//# sourceMappingURL=EnhancedEmbeddingService.js.map

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

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

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

@@ -0,0 +1,163 @@
+/**
+ * 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
+ */
+type Database = any;
+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;
+    constructor(db: Database);
+    /**
+     * Create a recall certificate for a retrieval operation
+     */
+    createCertificate(params: {
+        queryId: string;
+        queryText: string;
+        chunks: Array<{
+            id: string;
+            type: string;
+            content: string;
+            relevance: number;
+        }>;
+        requirements: string[];
+        accessLevel?: string;
+    }): 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/src/controllers/ExplainableRecall.d.ts.map

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