cozo-memory 1.1.2 → 1.1.4

package/dist/inference-engine.js

@@ -176,88 +176,116 @@ class InferenceEngine {
      * @param minSimilarity Minimum similarity for semantic jumps (0.0 - 1.0, Default: 0.7)
      */
     async semanticGraphWalk(startEntityId, maxDepth = 3, minSimilarity = 0.7) {
-        try {
-            // Get embedding of the start entity for the first semantic jump
-            const entityRes = await this.db.run('?[embedding] := *entity{id: $id, embedding, @ "NOW"}', { id: startEntityId });
-            if (entityRes.rows.length === 0)
+        // Limit max_depth to 2 to prevent database lock issues with complex queries
+        const safeMaxDepth = Math.min(maxDepth, 2);
+        if (maxDepth > 2) {
+            console.error(`[SemanticWalk] Limiting max_depth from ${maxDepth} to 2 to prevent database locks`);
+        }
+        // Retry logic with exponential backoff for database lock errors
+        const maxRetries = 3;
+        const baseDelay = 100; // ms
+        const timeout = 30000; // 30 second timeout
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                // Wrap in timeout promise
+                const result = await Promise.race([
+                    this._executeSemanticWalk(startEntityId, safeMaxDepth, minSimilarity),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('Semantic walk timeout')), timeout))
+                ]);
+                return result;
+            }
+            catch (e) {
+                const isLockError = e.message?.includes('database is locked') || e.message?.includes('code 5');
+                const isLastAttempt = attempt === maxRetries - 1;
+                if (isLockError && !isLastAttempt) {
+                    const delay = baseDelay * Math.pow(2, attempt);
+                    console.error(`[SemanticWalk] Database locked (attempt ${attempt + 1}/${maxRetries}), retrying in ${delay}ms...`);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    continue;
+                }
+                console.error(`[SemanticWalk] Failed after ${attempt + 1} attempts:`, e.message);
                 return [];
-            const startEmbedding = entityRes.rows[0][0];
-            // Recursive Datalog query
-            // We avoid complex aggregation of strings in Datalog as this can cause errors.
-            // Instead, we implicitly group by 'type' as well and filter later in JS.
-            const query = `
-        # 1. Start point
-        path[id, depth, score, type] := 
-          id = $startId, 
-          depth = 0, 
-          score = 1.0, 
-          type = 'start'
+            }
+        }
+        return [];
+    }
+    async _executeSemanticWalk(startEntityId, maxDepth, minSimilarity) {
+        // Get embedding of the start entity for the first semantic jump
+        // Optimized: Remove @ "NOW" validity check for better performance
+        const entityRes = await this.db.run('?[embedding] := *entity{id: $id, embedding}', { id: startEntityId });
+        if (entityRes.rows.length === 0)
+            return [];
+        const startEmbedding = entityRes.rows[0][0];
+        // Recursive Datalog query - Optimized for performance
+        // Removed @ "NOW" validity checks to reduce lock contention
+        const query = `
+      # 1. Start point
+      path[id, depth, score, type] := 
+        id = $startId, 
+        depth = 0, 
+        score = 1.0, 
+        type = 'start'
 
-        # 2. Recursion: Follow explicit relations
-        path[next_id, new_depth, new_score, new_type] :=
-          path[curr_id, depth, score, curr_type],
-          depth < $maxDepth,
-          *relationship{from_id: curr_id, to_id: next_id, relation_type, strength, @ "NOW"},
-          new_depth = depth + 1,
-          new_score = score * strength,
-          new_type = if(curr_type == 'start', 'explicit', if(curr_type == 'explicit', 'explicit', 'mixed'))
+      # 2. Recursion: Follow explicit relations (optimized - no validity check)
+      path[next_id, new_depth, new_score, new_type] :=
+        path[curr_id, depth, score, curr_type],
+        depth < $maxDepth,
+        *relationship{from_id: curr_id, to_id: next_id, relation_type, strength},
+        new_depth = depth + 1,
+        new_score = score * strength,
+        new_type = if(curr_type == 'start', 'explicit', if(curr_type == 'explicit', 'explicit', 'mixed'))
 
-        # 3. Recursion: Follow semantic similarity (via HNSW Index)
-        path[next_id, new_depth, new_score, new_type] :=
-          path[curr_id, depth, score, curr_type],
-          depth < $maxDepth,
-          *entity{id: curr_id, embedding: curr_emb, @ "NOW"}, # Load embedding
-          # Search for the K nearest neighbors to the current embedding
-          ~entity:semantic { id: next_id |
-            query: curr_emb,
-            k: 5,
-            ef: 20,
-            bind_distance: dist
-          },
-          next_id != curr_id, # No self-reference
-          sim = 1.0 - dist,
-          sim >= $minSim,
-          new_depth = depth + 1,
-          new_score = score * sim * 0.8, # Penalize semantic jumps slightly (damping)
-          new_type = if(curr_type == 'start', 'semantic', if(curr_type == 'semantic', 'semantic', 'mixed'))
+      # 3. Recursion: Follow semantic similarity (optimized - no validity check)
+      path[next_id, new_depth, new_score, new_type] :=
+        path[curr_id, depth, score, curr_type],
+        depth < $maxDepth,
+        *entity{id: curr_id, embedding: curr_emb},
+        # Search for the K nearest neighbors to the current embedding
+        ~entity:semantic { id: next_id |
+          query: curr_emb,
+          k: 5,
+          ef: 20,
+          bind_distance: dist
+        },
+        next_id != curr_id,
+        sim = 1.0 - dist,
+        sim >= $minSim,
+        new_depth = depth + 1,
+        new_score = score * sim * 0.8,
+        new_type = if(curr_type == 'start', 'semantic', if(curr_type == 'semantic', 'semantic', 'mixed'))
 
-        # Aggregate result (Grouping by ID and Type)
-        ?[id, min_depth, max_score, type] := 
-          path[id, d, s, type],
-          id != $startId,
-          min_depth = min(d),
-          max_score = max(s)
-          :limit 100
-      `;
-            const res = await this.db.run(query, {
-                startId: startEntityId,
-                maxDepth: maxDepth,
-                minSim: minSimilarity
-            });
-            // Post-processing in JS: Select best path type per ID
-            const bestPaths = new Map();
-            for (const row of res.rows) {
-                const [id, depth, score, type] = row;
-                // Cozo sometimes returns arrays or raw values, ensure we have Strings/Numbers
-                const cleanId = String(id);
-                const cleanDepth = Number(depth);
-                const cleanScore = Number(score);
-                const cleanType = String(type);
-                if (!bestPaths.has(cleanId) || cleanScore > bestPaths.get(cleanId).path_score) {
-                    bestPaths.set(cleanId, {
-                        entity_id: cleanId,
-                        distance: cleanDepth,
-                        path_score: cleanScore,
-                        path_type: cleanType
-                    });
-                }
+      # Aggregate result (Grouping by ID and Type)
+      ?[id, min_depth, max_score, type] := 
+        path[id, d, s, type],
+        id != $startId,
+        min_depth = min(d),
+        max_score = max(s)
+        :limit 100
+    `;
+        const res = await this.db.run(query, {
+            startId: startEntityId,
+            maxDepth: maxDepth,
+            minSim: minSimilarity
+        });
+        // Post-processing in JS: Select best path type per ID
+        const bestPaths = new Map();
+        for (const row of res.rows) {
+            const [id, depth, score, type] = row;
+            // Cozo sometimes returns arrays or raw values, ensure we have Strings/Numbers
+            const cleanId = String(id);
+            const cleanDepth = Number(depth);
+            const cleanScore = Number(score);
+            const cleanType = String(type);
+            if (!bestPaths.has(cleanId) || cleanScore > bestPaths.get(cleanId).path_score) {
+                bestPaths.set(cleanId, {
+                    entity_id: cleanId,
+                    distance: cleanDepth,
+                    path_score: cleanScore,
+                    path_type: cleanType
+                });
             }
-            return Array.from(bestPaths.values());
-        }
-        catch (e) {
-            console.error("Semantic Graph Walk Failed:", e.message);
-            return [];
         }
+        return Array.from(bestPaths.values());
     }
     /**
      * Analyzes the cluster structure directly on the HNSW graph (Layer 0).

package/dist/logical-edges-service.js

@@ -0,0 +1,316 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogicalEdgesService = void 0;
+/**
+ * Logical Edges Service (v1.0)
+ *
+ * Discovers implicit relationships from entity metadata using logical inference rules.
+ *
+ * Research Foundation:
+ * - SAGE (ICLR 2026): Implicit graph exploration with on-demand edge discovery
+ * - Metadata Knowledge Graphs (Atlan 2026): Metadata-driven relationship inference
+ * - Knowledge Graph Completion (Frontiers 2025): Predicting implicit relationships
+ *
+ * Patterns:
+ * 1. **Metadata-Based Edges**: Same category, type, domain, etc.
+ * 2. **Semantic Edges**: Entities with similar metadata patterns
+ * 3. **Hierarchical Edges**: Parent-child relationships from metadata
+ * 4. **Contextual Edges**: Time-based, location-based, or domain-based grouping
+ * 5. **Transitive Edges**: Derived from existing relationships + metadata
+ */
+class LogicalEdgesService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Discover all logical edges for an entity based on metadata patterns
+     */
+    async discoverLogicalEdges(entityId) {
+        const edges = [];
+        // 1. Same Category Edges
+        const categoryEdges = await this.findSameCategoryEdges(entityId);
+        edges.push(...categoryEdges);
+        // 2. Same Type Edges
+        const typeEdges = await this.findSameTypeEdges(entityId);
+        edges.push(...typeEdges);
+        // 3. Hierarchical Edges (parent-child from metadata)
+        const hierarchicalEdges = await this.findHierarchicalEdges(entityId);
+        edges.push(...hierarchicalEdges);
+        // 4. Contextual Edges (domain, time period, location)
+        const contextualEdges = await this.findContextualEdges(entityId);
+        edges.push(...contextualEdges);
+        // 5. Transitive Edges (derived from relationships + metadata)
+        const transitiveEdges = await this.findTransitiveLogicalEdges(entityId);
+        edges.push(...transitiveEdges);
+        // Deduplicate and return
+        return this.deduplicateEdges(edges);
+    }
+    /**
+     * Pattern 1: Same Category Edges
+     *
+     * Entities with the same category metadata are logically related
+     * Example: All "Machine Learning" papers are related
+     */
+    async findSameCategoryEdges(entityId) {
+        try {
+            const query = `
+        # Get the category of the target entity
+        source_category[category] :=
+          *entity{id: $entity_id, metadata, @ "NOW"},
+          category = get(metadata, 'category')
+
+        # Find all entities with the same category
+        ?[other_id, other_name, other_type, confidence, reason] :=
+          source_category[category],
+          category != null,
+          *entity{id: other_id, name: other_name, type: other_type, metadata, @ "NOW"},
+          other_id != $entity_id,
+          get(metadata, 'category') == category,
+          confidence = 0.8,
+          reason = concat('Same category: ', category)
+      `;
+            const result = await this.db.run(query, { entity_id: entityId });
+            return result.rows.map((r) => ({
+                from_id: entityId,
+                to_id: r[0],
+                relation_type: "same_category",
+                confidence: r[3],
+                reason: r[4],
+                pattern: "metadata_category"
+            }));
+        }
+        catch (error) {
+            console.error("[LogicalEdges] Same category error:", error.message);
+            return [];
+        }
+    }
+    /**
+     * Pattern 2: Same Type Edges
+     *
+     * Entities of the same type are logically related
+     * Example: All "Person" entities, all "Project" entities
+     */
+    async findSameTypeEdges(entityId) {
+        try {
+            const query = `
+        # Get the type of the target entity
+        source_type[entity_type] :=
+          *entity{id: $entity_id, type: entity_type, @ "NOW"}
+
+        # Find all entities with the same type
+        ?[other_id, other_name, confidence, reason] :=
+          source_type[entity_type],
+          *entity{id: other_id, name: other_name, type: entity_type, @ "NOW"},
+          other_id != $entity_id,
+          confidence = 0.7,
+          reason = concat('Same type: ', entity_type)
+      `;
+            const result = await this.db.run(query, { entity_id: entityId });
+            return result.rows.map((r) => ({
+                from_id: entityId,
+                to_id: r[0],
+                relation_type: "same_type",
+                confidence: r[2],
+                reason: r[3],
+                pattern: "metadata_type"
+            }));
+        }
+        catch (error) {
+            console.error("[LogicalEdges] Same type error:", error.message);
+            return [];
+        }
+    }
+    /**
+     * Pattern 3: Hierarchical Edges
+     *
+     * Parent-child relationships derived from metadata hierarchy
+     * Example: "parent_id" in metadata indicates parent entity
+     */
+    async findHierarchicalEdges(entityId) {
+        try {
+            const query = `
+        # Get parent_id from metadata
+        source_parent[parent_id] :=
+          *entity{id: $entity_id, metadata, @ "NOW"},
+          parent_id = get(metadata, 'parent_id'),
+          parent_id != null
+
+        # Find parent entity
+        ?[parent_id, parent_name, confidence, reason] :=
+          source_parent[parent_id],
+          *entity{id: parent_id, name: parent_name, @ "NOW"},
+          confidence = 0.9,
+          reason = 'Parent relationship from metadata'
+
+        # Also find children (reverse direction)
+        ?[child_id, child_name, confidence, reason] :=
+          *entity{id: child_id, metadata, @ "NOW"},
+          get(metadata, 'parent_id') == $entity_id,
+          *entity{id: child_id, name: child_name, @ "NOW"},
+          confidence = 0.9,
+          reason = 'Child relationship from metadata'
+      `;
+            const result = await this.db.run(query, { entity_id: entityId });
+            return result.rows.map((r) => ({
+                from_id: entityId,
+                to_id: r[0],
+                relation_type: "hierarchical",
+                confidence: r[2],
+                reason: r[3],
+                pattern: "metadata_hierarchy"
+            }));
+        }
+        catch (error) {
+            console.error("[LogicalEdges] Hierarchical error:", error.message);
+            return [];
+        }
+    }
+    /**
+     * Pattern 4: Contextual Edges
+     *
+     * Entities sharing context (domain, time period, location, organization)
+     * Example: All papers from 2025, all entities in "AI" domain
+     */
+    async findContextualEdges(entityId) {
+        try {
+            // Simplified contextual edge discovery
+            // Find entities with same domain
+            const query = `
+        # Get domain from metadata
+        source_domain[domain] :=
+          *entity{id: $entity_id, metadata, @ "NOW"},
+          domain = get(metadata, 'domain'),
+          domain != null
+
+        # Find entities with matching domain
+        ?[other_id, other_name, confidence, reason] :=
+          source_domain[domain],
+          *entity{id: other_id, name: other_name, metadata, @ "NOW"},
+          other_id != $entity_id,
+          get(metadata, 'domain') == domain,
+          confidence = 0.75,
+          reason = concat('Same domain: ', domain)
+      `;
+            const result = await this.db.run(query, { entity_id: entityId });
+            return result.rows.map((r) => ({
+                from_id: entityId,
+                to_id: r[0],
+                relation_type: "contextual",
+                confidence: r[2],
+                reason: r[3],
+                pattern: "metadata_context"
+            }));
+        }
+        catch (error) {
+            console.error("[LogicalEdges] Contextual error:", error.message);
+            return [];
+        }
+    }
+    /**
+     * Pattern 5: Transitive Logical Edges
+     *
+     * Derived from existing relationships combined with metadata patterns
+     * Example: If A -> B (explicit) and B has same category as C, then A -> C (transitive)
+     */
+    async findTransitiveLogicalEdges(entityId) {
+        try {
+            const query = `
+        # Get entities connected via explicit relationships
+        connected[mid_id] :=
+          *relationship{from_id: $entity_id, to_id: mid_id, @ "NOW"}
+
+        # Get metadata of connected entities
+        connected_metadata[mid_id, mid_category, mid_type] :=
+          connected[mid_id],
+          *entity{id: mid_id, type: mid_type, metadata, @ "NOW"},
+          mid_category = get(metadata, 'category')
+
+        # Find entities with same category as connected entities
+        ?[other_id, other_name, confidence, reason] :=
+          connected_metadata[mid_id, category, _],
+          category != null,
+          *entity{id: other_id, name: other_name, metadata, @ "NOW"},
+          other_id != $entity_id,
+          other_id != mid_id,
+          get(metadata, 'category') == category,
+          confidence = 0.6,
+          reason = concat('Transitive via category match through ', mid_id)
+
+        # Find entities with same type as connected entities
+        ?[other_id, other_name, confidence, reason] :=
+          connected_metadata[mid_id, _, entity_type],
+          *entity{id: other_id, name: other_name, type: entity_type, @ "NOW"},
+          other_id != $entity_id,
+          other_id != mid_id,
+          confidence = 0.55,
+          reason = concat('Transitive via type match through ', mid_id)
+      `;
+            const result = await this.db.run(query, { entity_id: entityId });
+            return result.rows.map((r) => ({
+                from_id: entityId,
+                to_id: r[0],
+                relation_type: "transitive_logical",
+                confidence: r[2],
+                reason: r[3],
+                pattern: "metadata_transitive"
+            }));
+        }
+        catch (error) {
+            console.error("[LogicalEdges] Transitive error:", error.message);
+            return [];
+        }
+    }
+    /**
+     * Deduplicate edges by (from_id, to_id, relation_type)
+     * Keep the one with highest confidence
+     */
+    deduplicateEdges(edges) {
+        const map = new Map();
+        for (const edge of edges) {
+            const key = `${edge.from_id}|${edge.to_id}|${edge.relation_type}`;
+            const existing = map.get(key);
+            if (!existing || edge.confidence > existing.confidence) {
+                map.set(key, edge);
+            }
+        }
+        return Array.from(map.values());
+    }
+    /**
+     * Create logical edges as explicit relationships in the database
+     * (Optional: for performance optimization)
+     */
+    async materializeLogicalEdges(entityId) {
+        try {
+            const edges = await this.discoverLogicalEdges(entityId);
+            let created = 0;
+            for (const edge of edges) {
+                try {
+                    const now = Date.now() * 1000;
+                    await this.db.run(`?[from_id, to_id, relation_type, created_at, strength, metadata] <- [
+              [$from_id, $to_id, $rel_type, [${now}, true], $strength, $metadata]
+            ] :insert relationship {from_id, to_id, relation_type, created_at => strength, metadata}`, {
+                        from_id: edge.from_id,
+                        to_id: edge.to_id,
+                        rel_type: edge.relation_type,
+                        strength: edge.confidence,
+                        metadata: { logical_edge: true, pattern: edge.pattern, reason: edge.reason }
+                    });
+                    created++;
+                }
+                catch (e) {
+                    // Ignore duplicate key errors
+                    if (!e.message?.includes("duplicate")) {
+                        console.error("[LogicalEdges] Materialization error:", e.message);
+                    }
+                }
+            }
+            return created;
+        }
+        catch (error) {
+            console.error("[LogicalEdges] Materialization failed:", error.message);
+            return 0;
+        }
+    }
+}
+exports.LogicalEdgesService = LogicalEdgesService;