cozo-memory 1.1.6 → 1.1.8

package/dist/query-pipeline.js

@@ -0,0 +1,355 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PipelineBuilder = exports.QueryPipeline = exports.postProcessStages = exports.rerankStages = exports.searchStages = exports.preprocessStages = void 0;
+exports.createStandardPipeline = createStandardPipeline;
+exports.createGraphRagPipeline = createGraphRagPipeline;
+exports.createAgenticPipeline = createAgenticPipeline;
+// Built-in Preprocessing Stages
+exports.preprocessStages = {
+    embedQuery: (embeddingService) => ({
+        type: 'preprocess',
+        name: 'embed-query',
+        enabled: true,
+        execute: async (ctx) => {
+            const start = Date.now();
+            ctx.embedding = await embeddingService.embed(ctx.query);
+            ctx.metrics['preprocess.embedding'] = Date.now() - start;
+            return ctx;
+        }
+    }),
+    queryNormalization: () => ({
+        type: 'preprocess',
+        name: 'query-normalization',
+        enabled: true,
+        execute: async (ctx) => {
+            const start = Date.now();
+            ctx.query = ctx.query.trim().toLowerCase();
+            ctx.metrics['preprocess.normalization'] = Date.now() - start;
+            return ctx;
+        }
+    })
+};
+// Built-in Search Stages
+exports.searchStages = {
+    hybridSearch: (hybridSearch) => ({
+        type: 'search',
+        name: 'hybrid-search',
+        enabled: true,
+        params: { limit: 10 },
+        execute: async (ctx) => {
+            const start = Date.now();
+            const limit = ctx.metadata.limit || 10;
+            ctx.results = await hybridSearch.search({
+                query: ctx.query,
+                limit,
+                includeEntities: true,
+                includeObservations: true
+            });
+            ctx.metrics['search.hybrid'] = Date.now() - start;
+            return ctx;
+        }
+    }),
+    graphRag: (hybridSearch) => ({
+        type: 'search',
+        name: 'graph-rag',
+        enabled: true,
+        params: { maxDepth: 3, limit: 10 },
+        execute: async (ctx) => {
+            const start = Date.now();
+            const limit = ctx.metadata.limit || 10;
+            ctx.results = await hybridSearch.graphRag({
+                query: ctx.query,
+                limit,
+                graphConstraints: {
+                    maxDepth: ctx.metadata.maxDepth || 3
+                }
+            });
+            ctx.metrics['search.graphRag'] = Date.now() - start;
+            return ctx;
+        }
+    }),
+    agenticSearch: (hybridSearch) => ({
+        type: 'search',
+        name: 'agentic-search',
+        enabled: true,
+        params: { limit: 10 },
+        execute: async (ctx) => {
+            const start = Date.now();
+            const limit = ctx.metadata.limit || 10;
+            ctx.results = await hybridSearch.agenticRetrieve({
+                query: ctx.query,
+                limit
+            });
+            ctx.metrics['search.agentic'] = Date.now() - start;
+            return ctx;
+        }
+    })
+};
+// Built-in Reranking Stages
+exports.rerankStages = {
+    crossEncoder: (reranker) => ({
+        type: 'rerank',
+        name: 'cross-encoder',
+        enabled: true,
+        execute: async (ctx) => {
+            const start = Date.now();
+            if (!ctx.results || ctx.results.length === 0) {
+                return ctx;
+            }
+            ctx.results = await reranker.rerank(ctx.query, ctx.results);
+            ctx.metrics['rerank.crossEncoder'] = Date.now() - start;
+            return ctx;
+        }
+    }),
+    diversityRerank: () => ({
+        type: 'rerank',
+        name: 'diversity-rerank',
+        enabled: true,
+        params: { diversityWeight: 0.3 },
+        execute: async (ctx) => {
+            const start = Date.now();
+            if (!ctx.results || ctx.results.length === 0) {
+                return ctx;
+            }
+            // MMR-style diversity reranking
+            const diversityWeight = ctx.metadata.diversityWeight || 0.3;
+            const reranked = [];
+            const remaining = [...ctx.results];
+            while (remaining.length > 0 && reranked.length < ctx.results.length) {
+                let bestIdx = 0;
+                let bestScore = -Infinity;
+                for (let i = 0; i < remaining.length; i++) {
+                    const candidate = remaining[i];
+                    const relevance = candidate.score || 0;
+                    // Calculate diversity (min similarity to already selected)
+                    let minSim = 1.0;
+                    for (const selected of reranked) {
+                        const sim = cosineSimilarity(candidate.embedding || [], selected.embedding || []);
+                        minSim = Math.min(minSim, sim);
+                    }
+                    const score = (1 - diversityWeight) * relevance + diversityWeight * (1 - minSim);
+                    if (score > bestScore) {
+                        bestScore = score;
+                        bestIdx = i;
+                    }
+                }
+                reranked.push(remaining.splice(bestIdx, 1)[0]);
+            }
+            ctx.results = reranked;
+            ctx.metrics['rerank.diversity'] = Date.now() - start;
+            return ctx;
+        }
+    })
+};
+// Built-in Post-processing Stages
+exports.postProcessStages = {
+    deduplication: () => ({
+        type: 'postprocess',
+        name: 'deduplication',
+        enabled: true,
+        params: { threshold: 0.95 },
+        execute: async (ctx) => {
+            const start = Date.now();
+            if (!ctx.results || ctx.results.length === 0) {
+                return ctx;
+            }
+            const threshold = ctx.metadata.dedupThreshold || 0.95;
+            const deduplicated = [];
+            for (const result of ctx.results) {
+                let isDuplicate = false;
+                for (const existing of deduplicated) {
+                    if (result.entity_id === existing.entity_id) {
+                        isDuplicate = true;
+                        break;
+                    }
+                    const sim = cosineSimilarity(result.embedding || [], existing.embedding || []);
+                    if (sim >= threshold) {
+                        isDuplicate = true;
+                        break;
+                    }
+                }
+                if (!isDuplicate) {
+                    deduplicated.push(result);
+                }
+            }
+            ctx.results = deduplicated;
+            ctx.metrics['postprocess.deduplication'] = Date.now() - start;
+            return ctx;
+        }
+    }),
+    scoreNormalization: () => ({
+        type: 'postprocess',
+        name: 'score-normalization',
+        enabled: true,
+        execute: async (ctx) => {
+            const start = Date.now();
+            if (!ctx.results || ctx.results.length === 0) {
+                return ctx;
+            }
+            const scores = ctx.results.map(r => r.score || 0);
+            const maxScore = Math.max(...scores);
+            const minScore = Math.min(...scores);
+            const range = maxScore - minScore;
+            if (range > 0) {
+                ctx.results = ctx.results.map(r => ({
+                    ...r,
+                    score: (r.score - minScore) / range
+                }));
+            }
+            ctx.metrics['postprocess.normalization'] = Date.now() - start;
+            return ctx;
+        }
+    }),
+    topK: () => ({
+        type: 'postprocess',
+        name: 'top-k',
+        enabled: true,
+        params: { k: 10 },
+        execute: async (ctx) => {
+            const start = Date.now();
+            const k = ctx.metadata.topK || 10;
+            if (ctx.results && ctx.results.length > k) {
+                ctx.results = ctx.results.slice(0, k);
+            }
+            ctx.metrics['postprocess.topK'] = Date.now() - start;
+            return ctx;
+        }
+    })
+};
+// Pipeline Executor
+class QueryPipeline {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async execute(query, metadata = {}) {
+        const ctx = {
+            query,
+            metadata: { ...metadata },
+            metrics: {},
+            results: []
+        };
+        const pipelineStart = Date.now();
+        for (const stage of this.config.stages) {
+            if (!stage.enabled) {
+                continue;
+            }
+            // Check condition if present
+            if (stage.condition && !stage.condition(ctx)) {
+                console.log(`[Pipeline] Skipping stage ${stage.name} (condition not met)`);
+                continue;
+            }
+            try {
+                const stageStart = Date.now();
+                await stage.execute(ctx);
+                ctx.metrics[`stage.${stage.name}`] = Date.now() - stageStart;
+            }
+            catch (error) {
+                console.error(`[Pipeline] Error in stage ${stage.name}:`, error);
+                ctx.metadata[`error.${stage.name}`] = String(error);
+            }
+        }
+        ctx.metrics['pipeline.total'] = Date.now() - pipelineStart;
+        return {
+            results: ctx.results || [],
+            metrics: ctx.metrics,
+            metadata: ctx.metadata
+        };
+    }
+    // A/B Testing support
+    async executeWithVariants(query, metadata = {}) {
+        if (!this.config.abTest?.enabled) {
+            return { primary: await this.execute(query, metadata) };
+        }
+        const primary = await this.execute(query, metadata);
+        // Execute variant pipelines if configured
+        const variants = {};
+        if (this.config.abTest.variants) {
+            for (const variant of this.config.abTest.variants) {
+                variants[variant] = await this.execute(query, { ...metadata, variant });
+            }
+        }
+        return { primary, variants };
+    }
+}
+exports.QueryPipeline = QueryPipeline;
+// Helper: Cosine Similarity
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    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 denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dotProduct / denominator;
+}
+// Pipeline Builder for easy construction
+class PipelineBuilder {
+    stages = [];
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    addStage(stage) {
+        this.stages.push(stage);
+        return this;
+    }
+    addPreprocess(stage) {
+        return this.addStage(stage);
+    }
+    addSearch(stage) {
+        return this.addStage(stage);
+    }
+    addRerank(stage) {
+        return this.addStage(stage);
+    }
+    addPostProcess(stage) {
+        return this.addStage(stage);
+    }
+    build() {
+        return {
+            name: this.name,
+            stages: this.stages
+        };
+    }
+}
+exports.PipelineBuilder = PipelineBuilder;
+// Preset Pipelines
+function createStandardPipeline(hybridSearch, embeddingService, reranker) {
+    const config = new PipelineBuilder('standard')
+        .addPreprocess(exports.preprocessStages.queryNormalization())
+        .addPreprocess(exports.preprocessStages.embedQuery(embeddingService))
+        .addSearch(exports.searchStages.hybridSearch(hybridSearch))
+        .addRerank(exports.rerankStages.crossEncoder(reranker))
+        .addPostProcess(exports.postProcessStages.deduplication())
+        .addPostProcess(exports.postProcessStages.topK())
+        .build();
+    return new QueryPipeline(config);
+}
+function createGraphRagPipeline(hybridSearch, embeddingService) {
+    const config = new PipelineBuilder('graph-rag')
+        .addPreprocess(exports.preprocessStages.embedQuery(embeddingService))
+        .addSearch(exports.searchStages.graphRag(hybridSearch))
+        .addRerank(exports.rerankStages.diversityRerank())
+        .addPostProcess(exports.postProcessStages.deduplication())
+        .addPostProcess(exports.postProcessStages.scoreNormalization())
+        .addPostProcess(exports.postProcessStages.topK())
+        .build();
+    return new QueryPipeline(config);
+}
+function createAgenticPipeline(hybridSearch, embeddingService, reranker) {
+    const config = new PipelineBuilder('agentic')
+        .addPreprocess(exports.preprocessStages.queryNormalization())
+        .addPreprocess(exports.preprocessStages.embedQuery(embeddingService))
+        .addSearch(exports.searchStages.agenticSearch(hybridSearch))
+        .addRerank(exports.rerankStages.crossEncoder(reranker))
+        .addPostProcess(exports.postProcessStages.deduplication())
+        .addPostProcess(exports.postProcessStages.topK())
+        .build();
+    return new QueryPipeline(config);
+}

package/dist/spreading-activation.js

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpreadingActivationService = void 0;
+class SpreadingActivationService {
+    db;
+    embeddings;
+    config;
+    constructor(db, embeddings, config = {}) {
+        this.db = db;
+        this.embeddings = embeddings;
+        this.config = {
+            spreadingFactor: config.spreadingFactor ?? 0.8,
+            decayFactor: config.decayFactor ?? 0.5,
+            temporalDecay: config.temporalDecay ?? 0.01,
+            inhibitionBeta: config.inhibitionBeta ?? 0.15,
+            inhibitionTopM: config.inhibitionTopM ?? 7,
+            propagationSteps: config.propagationSteps ?? 3,
+            activationThreshold: config.activationThreshold ?? 0.01,
+            sigmoidGamma: config.sigmoidGamma ?? 5.0,
+            sigmoidTheta: config.sigmoidTheta ?? 0.5,
+        };
+    }
+    /**
+     * Perform spreading activation from seed nodes
+     */
+    async spreadActivation(query, seedTopK = 5) {
+        try {
+            // Step 1: Initialize - Find seed nodes via dual trigger (BM25 + Semantic)
+            const queryEmbedding = await this.embeddings.embed(query);
+            const seedNodes = await this.findSeedNodes(query, queryEmbedding, seedTopK);
+            if (seedNodes.length === 0) {
+                console.error('[SpreadingActivation] No seed nodes found');
+                return {
+                    scores: [],
+                    iterations: 0,
+                    converged: false,
+                    seedNodes: [],
+                };
+            }
+            // Step 2: Initialize activation vector
+            let activation = new Map();
+            for (const seed of seedNodes) {
+                activation.set(seed.id, seed.score);
+            }
+            // Step 3: Propagate activation for T steps
+            let converged = false;
+            let iteration = 0;
+            for (iteration = 0; iteration < this.config.propagationSteps; iteration++) {
+                const newActivation = await this.propagateStep(activation);
+                // Check convergence (activation change < threshold)
+                const maxChange = this.calculateMaxChange(activation, newActivation);
+                if (maxChange < 0.001) {
+                    converged = true;
+                    break;
+                }
+                activation = newActivation;
+            }
+            // Step 4: Convert to result format
+            const scores = [];
+            for (const [entityId, act] of activation.entries()) {
+                if (act >= this.config.activationThreshold) {
+                    const isSeed = seedNodes.some(s => s.id === entityId);
+                    scores.push({
+                        entityId,
+                        activation: act,
+                        potential: act, // After sigmoid, potential ≈ activation
+                        source: isSeed ? 'seed' : 'propagated',
+                        hops: isSeed ? 0 : iteration,
+                    });
+                }
+            }
+            // Sort by activation (highest first)
+            scores.sort((a, b) => b.activation - a.activation);
+            return {
+                scores,
+                iterations: iteration + 1,
+                converged,
+                seedNodes: seedNodes.map(s => s.id),
+            };
+        }
+        catch (error) {
+            console.error('[SpreadingActivation] Error in spreadActivation:', error);
+            return {
+                scores: [],
+                iterations: 0,
+                converged: false,
+                seedNodes: [],
+            };
+        }
+    }
+    /**
+     * Find seed nodes using dual trigger: BM25 (lexical) + Semantic (dense)
+     */
+    async findSeedNodes(query, queryEmbedding, topK) {
+        try {
+            // Get all entities
+            const allEntities = await this.db.run(`
+        ?[id, name, embedding] :=
+          *entity{id, name, embedding}
+      `);
+            const scores = new Map();
+            // Calculate semantic similarity for each entity
+            for (const row of allEntities.rows) {
+                const [id, name, embedding] = row;
+                const entityEmbedding = embedding;
+                // Lexical score: simple keyword matching
+                const nameLower = name.toLowerCase();
+                const queryLower = query.toLowerCase();
+                const lexicalScore = nameLower.includes(queryLower) || queryLower.includes(nameLower) ? 1.0 : 0.0;
+                // Semantic score: cosine similarity
+                const semanticScore = this.cosineSimilarity(queryEmbedding, entityEmbedding);
+                // Combine scores (max of lexical and semantic)
+                const combinedScore = Math.max(lexicalScore, semanticScore);
+                scores.set(id, combinedScore);
+            }
+            // Sort and return top-K
+            return Array.from(scores.entries())
+                .map(([id, score]) => ({ id, score }))
+                .sort((a, b) => b.score - a.score)
+                .slice(0, topK);
+        }
+        catch (error) {
+            console.error('[SpreadingActivation] Error finding seed nodes:', error);
+            return [];
+        }
+    }
+    /**
+     * Calculate cosine similarity between two vectors
+     */
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length)
+            return 0;
+        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];
+        }
+        if (normA === 0 || normB === 0)
+            return 0;
+        return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
+    /**
+     * Single propagation step with Fan Effect, Lateral Inhibition, and Sigmoid
+     */
+    async propagateStep(currentActivation) {
+        try {
+            const now = Date.now();
+            const newPotential = new Map();
+            // Step 1: Propagation with Fan Effect
+            // For each active node, spread activation to neighbors
+            for (const [nodeId, activation] of currentActivation.entries()) {
+                if (activation < this.config.activationThreshold)
+                    continue;
+                // Get outgoing relationships
+                const relationships = await this.db.run(`
+          ?[from_id, to_id, strength, created_at] :=
+            *relationship{from_id, to_id, strength, created_at},
+            from_id == $node_id
+        `, { node_id: nodeId });
+                // Calculate fan (out-degree)
+                const fan = Math.max(1, relationships.rows.length);
+                // Propagate to each neighbor
+                for (const row of relationships.rows) {
+                    const [, toId, strength, createdAt] = row;
+                    const targetId = toId;
+                    // Calculate edge weight with temporal decay
+                    const timeDiff = (now - createdAt) / (1000 * 60 * 60 * 24); // days
+                    const temporalWeight = Math.exp(-this.config.temporalDecay * timeDiff);
+                    const edgeWeight = strength * temporalWeight;
+                    // Spread activation with fan effect
+                    const spreadAmount = (this.config.spreadingFactor * edgeWeight * activation) / fan;
+                    // Accumulate potential
+                    const currentPotential = newPotential.get(targetId) || 0;
+                    newPotential.set(targetId, currentPotential + spreadAmount);
+                }
+                // Node decay: retain some of current activation
+                const retainedActivation = (1 - this.config.decayFactor) * activation;
+                const currentPotential = newPotential.get(nodeId) || 0;
+                newPotential.set(nodeId, currentPotential + retainedActivation);
+            }
+            // Step 2: Lateral Inhibition
+            // Top-M nodes inhibit weaker competitors
+            const potentialArray = Array.from(newPotential.entries())
+                .sort((a, b) => b[1] - a[1]);
+            const topM = potentialArray.slice(0, this.config.inhibitionTopM);
+            const inhibitedPotential = new Map();
+            for (const [nodeId, potential] of newPotential.entries()) {
+                let inhibition = 0;
+                // Calculate inhibition from top-M nodes
+                for (const [topId, topPotential] of topM) {
+                    if (topId !== nodeId && topPotential > potential) {
+                        inhibition += this.config.inhibitionBeta * (topPotential - potential);
+                    }
+                }
+                // Apply inhibition (cannot go below 0)
+                const inhibitedValue = Math.max(0, potential - inhibition);
+                inhibitedPotential.set(nodeId, inhibitedValue);
+            }
+            // Step 3: Sigmoid Activation Function
+            const newActivation = new Map();
+            for (const [nodeId, potential] of inhibitedPotential.entries()) {
+                const activation = this.sigmoid(potential);
+                if (activation >= this.config.activationThreshold) {
+                    newActivation.set(nodeId, activation);
+                }
+            }
+            return newActivation;
+        }
+        catch (error) {
+            console.error('[SpreadingActivation] Error in propagateStep:', error);
+            return currentActivation;
+        }
+    }
+    /**
+     * Sigmoid activation function: σ(u) = 1 / (1 + exp(-γ(u - θ)))
+     */
+    sigmoid(potential) {
+        const exponent = -this.config.sigmoidGamma * (potential - this.config.sigmoidTheta);
+        return 1 / (1 + Math.exp(exponent));
+    }
+    /**
+     * Calculate maximum activation change between iterations
+     */
+    calculateMaxChange(oldActivation, newActivation) {
+        let maxChange = 0;
+        // Check all nodes in both maps
+        const allNodes = new Set([...oldActivation.keys(), ...newActivation.keys()]);
+        for (const nodeId of allNodes) {
+            const oldValue = oldActivation.get(nodeId) || 0;
+            const newValue = newActivation.get(nodeId) || 0;
+            const change = Math.abs(newValue - oldValue);
+            maxChange = Math.max(maxChange, change);
+        }
+        return maxChange;
+    }
+    /**
+     * Triple Hybrid Retrieval: Semantic + Activation + PageRank
+     */
+    async tripleHybridRetrieval(query, options = {}) {
+        try {
+            const { topK = 30, lambdaSemantic = 0.5, lambdaActivation = 0.3, lambdaStructural = 0.2, seedTopK = 5, } = options;
+            // 1. Semantic similarity
+            const queryEmbedding = await this.embeddings.embed(query);
+            const allEntities = await this.db.run(`
+        ?[id, embedding] :=
+          *entity{id, embedding}
+      `);
+            const semanticScores = new Map();
+            for (const row of allEntities.rows) {
+                const [id, embedding] = row;
+                const score = this.cosineSimilarity(queryEmbedding, embedding);
+                semanticScores.set(id, score);
+            }
+            // 2. Spreading activation
+            const activationResult = await this.spreadActivation(query, seedTopK);
+            const activationScores = new Map();
+            for (const score of activationResult.scores) {
+                activationScores.set(score.entityId, score.activation);
+            }
+            // 3. PageRank (structural importance)
+            const pageRankResults = await this.db.run(`
+        ?[id, rank] :=
+          *entity_rank{entity_id: id, rank}
+      `);
+            const pageRankScores = new Map();
+            for (const row of pageRankResults.rows) {
+                const [id, rank] = row;
+                pageRankScores.set(id, rank);
+            }
+            // 4. Combine scores
+            const allEntityIds = new Set([
+                ...semanticScores.keys(),
+                ...activationScores.keys(),
+                ...pageRankScores.keys(),
+            ]);
+            const results = [];
+            for (const entityId of allEntityIds) {
+                const semantic = semanticScores.get(entityId) || 0;
+                const activation = activationScores.get(entityId) || 0;
+                const structural = pageRankScores.get(entityId) || 0;
+                const combinedScore = lambdaSemantic * semantic +
+                    lambdaActivation * activation +
+                    lambdaStructural * structural;
+                results.push({
+                    entityId,
+                    score: combinedScore,
+                    breakdown: {
+                        semantic,
+                        activation,
+                        structural,
+                        formula: `${lambdaSemantic}×${semantic.toFixed(3)} + ${lambdaActivation}×${activation.toFixed(3)} + ${lambdaStructural}×${structural.toFixed(3)}`,
+                    },
+                });
+            }
+            // Sort by combined score and return top-K
+            results.sort((a, b) => b.score - a.score);
+            return results.slice(0, topK);
+        }
+        catch (error) {
+            console.error('[SpreadingActivation] Error in tripleHybridRetrieval:', error);
+            return [];
+        }
+    }
+}
+exports.SpreadingActivationService = SpreadingActivationService;