rust-kgdb 0.3.1 → 0.3.3

package/README.md

@@ -14,8 +14,11 @@
 | Feature | Description |
 |---------|-------------|
 | **GraphDB** | Core RDF/SPARQL database with 100% W3C compliance |
-| **GraphFrames** | Spark-compatible graph analytics (PageRank, triangles, motifs) |
+| **GraphFrames** | Spark-compatible graph analytics (PageRank, triangles, components) |
+| **Motif Finding** | Graph pattern DSL for structural queries (fraud rings, recommendations) |
 | **EmbeddingService** | Vector similarity search, text search, multi-provider embeddings |
+| **Embedding Triggers** | Automatic embedding generation on INSERT/UPDATE/DELETE |
+| **Embedding Providers** | OpenAI, Voyage, Cohere, Anthropic, Mistral, Jina, Ollama, HF-TEI |
 | **DatalogProgram** | Rule-based reasoning with transitive closure |
 | **Pregel** | Bulk Synchronous Parallel graph processing |
 | **Hypergraph** | Native hyperedge support beyond RDF triples |
@@ -138,6 +141,121 @@ console.log('Star graph:', star.vertexCount(), 'vertices,', star.edgeCount(), 'e
 console.log('Cycle graph:', cycle.vertexCount(), 'vertices,', cycle.edgeCount(), 'edges')
 ```
 
+### 2b. Motif Pattern Matching (Graph Pattern DSL)
+
+Motifs are recurring structural patterns in graphs. rust-kgdb supports a powerful DSL for finding motifs:
+
+```javascript
+const { GraphFrame, completeGraph, chainGraph, cycleGraph, friendsGraph } = require('rust-kgdb')
+
+// === Basic Motif Syntax ===
+// (a)-[]->(b)              Single edge from a to b
+// (a)-[e]->(b)             Named edge 'e' from a to b
+// (a)-[]->(b); (b)-[]->(c) Two-hop path (chain pattern)
+// !(a)-[]->(b)             Negation (edge does NOT exist)
+
+// === Find Single Edges ===
+const chain = chainGraph(5)  // v0 -> v1 -> v2 -> v3 -> v4
+const edges = JSON.parse(chain.find("(a)-[]->(b)"))
+console.log('All edges:', edges.length)  // 4
+
+// === Two-Hop Paths (Friend-of-Friend Pattern) ===
+const twoHop = JSON.parse(chain.find("(a)-[]->(b); (b)-[]->(c)"))
+console.log('Two-hop paths:', twoHop.length)  // 3
+// v0->v1->v2, v1->v2->v3, v2->v3->v4
+
+// === Three-Hop Paths ===
+const threeHop = JSON.parse(chain.find("(a)-[]->(b); (b)-[]->(c); (c)-[]->(d)"))
+console.log('Three-hop paths:', threeHop.length)  // 2
+
+// === Triangle Pattern (Cycle of Length 3) ===
+const k4 = completeGraph(4)  // K4 has triangles
+const triangles = JSON.parse(k4.find("(a)-[]->(b); (b)-[]->(c); (c)-[]->(a)"))
+// Filter to avoid counting same triangle multiple times
+const uniqueTriangles = triangles.filter(t => t.a < t.b && t.b < t.c)
+console.log('Triangles in K4:', uniqueTriangles.length)  // 4
+
+// === Star Pattern (Hub with Multiple Spokes) ===
+const social = new GraphFrame(
+  JSON.stringify([
+    {id: "influencer"},
+    {id: "follower1"}, {id: "follower2"}, {id: "follower3"}
+  ]),
+  JSON.stringify([
+    {src: "influencer", dst: "follower1"},
+    {src: "influencer", dst: "follower2"},
+    {src: "influencer", dst: "follower3"}
+  ])
+)
+// Find hub pattern: someone with 2+ outgoing edges
+const hubPattern = JSON.parse(social.find("(hub)-[]->(f1); (hub)-[]->(f2)"))
+console.log('Hub patterns (2+ followers):', hubPattern.length)
+
+// === Reciprocal Relationship (Mutual Friends) ===
+const mutual = new GraphFrame(
+  JSON.stringify([{id: "alice"}, {id: "bob"}, {id: "carol"}]),
+  JSON.stringify([
+    {src: "alice", dst: "bob"},
+    {src: "bob", dst: "alice"},  // Reciprocal
+    {src: "bob", dst: "carol"}   // One-way
+  ])
+)
+const reciprocal = JSON.parse(mutual.find("(a)-[]->(b); (b)-[]->(a)"))
+console.log('Mutual relationships:', reciprocal.length)  // 2 (alice<->bob counted twice)
+
+// === Diamond Pattern (Common in Fraud Detection) ===
+// A -> B, A -> C, B -> D, C -> D (convergence point D)
+const diamond = new GraphFrame(
+  JSON.stringify([{id: "A"}, {id: "B"}, {id: "C"}, {id: "D"}]),
+  JSON.stringify([
+    {src: "A", dst: "B"},
+    {src: "A", dst: "C"},
+    {src: "B", dst: "D"},
+    {src: "C", dst: "D"}
+  ])
+)
+const diamondPattern = JSON.parse(diamond.find(
+  "(a)-[]->(b); (a)-[]->(c); (b)-[]->(d); (c)-[]->(d)"
+))
+console.log('Diamond patterns:', diamondPattern.length)  // 1
+
+// === Use Case: Fraud Ring Detection ===
+// Find circular money transfers: A -> B -> C -> A
+const transactions = new GraphFrame(
+  JSON.stringify([
+    {id: "acc001"}, {id: "acc002"}, {id: "acc003"}, {id: "acc004"}
+  ]),
+  JSON.stringify([
+    {src: "acc001", dst: "acc002", amount: 10000},
+    {src: "acc002", dst: "acc003", amount: 9900},
+    {src: "acc003", dst: "acc001", amount: 9800},  // Suspicious cycle!
+    {src: "acc003", dst: "acc004", amount: 5000}   // Normal transfer
+  ])
+)
+const cycles = JSON.parse(transactions.find(
+  "(a)-[]->(b); (b)-[]->(c); (c)-[]->(a)"
+))
+console.log('Circular transfer patterns:', cycles.length)  // Found fraud ring!
+
+// === Use Case: Recommendation (Friends-of-Friends not yet connected) ===
+const network = friendsGraph()
+const fofPattern = JSON.parse(network.find("(a)-[]->(b); (b)-[]->(c)"))
+// Filter: a != c and no direct edge a->c (potential recommendation)
+console.log('Friend-of-friend patterns for recommendations:', fofPattern.length)
+```
+
+### Motif Pattern Reference
+
+| Pattern | DSL Syntax | Description |
+|---------|------------|-------------|
+| **Edge** | `(a)-[]->(b)` | Single directed edge |
+| **Named Edge** | `(a)-[e]->(b)` | Edge with binding name |
+| **Two-hop** | `(a)-[]->(b); (b)-[]->(c)` | Path of length 2 |
+| **Triangle** | `(a)-[]->(b); (b)-[]->(c); (c)-[]->(a)` | 3-cycle |
+| **Star** | `(h)-[]->(a); (h)-[]->(b); (h)-[]->(c)` | Hub pattern |
+| **Diamond** | `(a)-[]->(b); (a)-[]->(c); (b)-[]->(d); (c)-[]->(d)` | Convergence |
+| **Negation** | `!(a)-[]->(b)` | Edge must NOT exist |
+
 ### 3. EmbeddingService (Vector Similarity & Text Search)
 
 ```javascript
@@ -178,6 +296,11 @@ console.log('Composite embedding:', composite ? 'stored' : 'not found')
 // Count composite embeddings
 console.log('Total composites:', service.countComposites())
 
+// === Composite Similarity Search (RRF Aggregation) ===
+// Find similar using Reciprocal Rank Fusion across multiple providers
+const compositeSimilar = JSON.parse(service.findSimilarComposite('product_123', 10, 0.5, 'rrf'))
+console.log('Similar (composite RRF):', compositeSimilar)
+
 // === Use Case: Semantic Product Search ===
 // Store product embeddings
 const products = ['laptop', 'phone', 'tablet', 'keyboard', 'mouse']
@@ -192,6 +315,91 @@ const relatedToLaptop = JSON.parse(service.findSimilar('laptop', 5, 0.0))
 console.log('Products similar to laptop:', relatedToLaptop)
 ```
 
+### 3b. Embedding Triggers (Automatic Embedding Generation)
+
+```javascript
+// Triggers automatically generate embeddings when data changes
+// Configure triggers to fire on INSERT/UPDATE/DELETE events
+
+// Example: Auto-embed new entities on insert
+const triggerConfig = {
+  name: 'auto_embed_on_insert',
+  event: 'AfterInsert',
+  action: {
+    type: 'GenerateEmbedding',
+    source: 'Subject',       // Embed the subject of the triple
+    provider: 'openai'       // Use OpenAI provider
+  }
+}
+
+// Multiple triggers for different providers
+const triggers = [
+  { name: 'embed_openai', provider: 'openai' },
+  { name: 'embed_voyage', provider: 'voyage' },
+  { name: 'embed_cohere', provider: 'cohere' }
+]
+
+// Each trigger fires independently, creating composite embeddings
+```
+
+### 3c. Embedding Providers (Multi-Provider Architecture)
+
+```javascript
+// rust-kgdb supports multiple embedding providers:
+//
+// Built-in Providers:
+// - 'openai'    → text-embedding-3-small (1536 or 384 dim)
+// - 'voyage'    → voyage-2, voyage-lite-02-instruct
+// - 'cohere'    → embed-v3
+// - 'anthropic' → Via Voyage partnership
+// - 'mistral'   → mistral-embed
+// - 'jina'      → jina-embeddings-v2
+// - 'ollama'    → Local models (llama, mistral, etc.)
+// - 'hf-tei'    → HuggingFace Text Embedding Inference
+//
+// Provider Configuration (Rust-side):
+
+const providerConfig = {
+  providers: {
+    openai: {
+      api_key: process.env.OPENAI_API_KEY,
+      model: 'text-embedding-3-small',
+      dimensions: 384
+    },
+    voyage: {
+      api_key: process.env.VOYAGE_API_KEY,
+      model: 'voyage-2',
+      dimensions: 1024
+    },
+    cohere: {
+      api_key: process.env.COHERE_API_KEY,
+      model: 'embed-english-v3.0',
+      dimensions: 384
+    },
+    ollama: {
+      base_url: 'http://localhost:11434',
+      model: 'nomic-embed-text',
+      dimensions: 768
+    }
+  },
+  default_provider: 'openai'
+}
+
+// Why Multi-Provider?
+// Google Research (arxiv.org/abs/2508.21038) shows single embeddings hit
+// a "recall ceiling" - different providers capture different semantic aspects:
+// - OpenAI: General semantic understanding
+// - Voyage: Domain-specific (legal, financial, code)
+// - Cohere: Multilingual support
+// - Ollama: Privacy-preserving local inference
+
+// Aggregation Strategies for composite search:
+// - 'rrf'     → Reciprocal Rank Fusion (recommended)
+// - 'max'     → Maximum score across providers
+// - 'avg'     → Weighted average
+// - 'voting'  → Consensus (entity must appear in N providers)
+```
+
 ### 4. DatalogProgram (Rule-Based Reasoning)
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "High-performance RDF/SPARQL database with GraphFrames analytics, vector embeddings, Datalog reasoning, and Pregel BSP processing",
   "main": "index.js",
   "types": "index.d.ts",