rust-kgdb 0.6.78 → 0.6.80

package/README.md

@@ -4,7 +4,24 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![W3C](https://img.shields.io/badge/W3C-SPARQL%201.1%20%7C%20RDF%201.2-blue)](https://www.w3.org/TR/sparql11-query/)
 
-> **Two-Layer Architecture**: High-performance Rust knowledge graph database + HyperMind neuro-symbolic agent framework with mathematical foundations.
+> **Enterprise Knowledge Graph with Native Graph Embeddings**: A production-grade RDF database featuring built-in RDF2Vec, multi-vector composite search, and distributed SPARQL execution—engineered for teams who need verifiable AI at scale.
+
+---
+
+## What's New in v0.6.79
+
+| Feature | Description | Performance |
+|---------|-------------|-------------|
+| **Rdf2VecEngine** | Native graph embeddings from random walks | 68 µs lookup (3,000x faster than APIs) |
+| **Composite Multi-Vector** | RRF fusion of RDF2Vec + OpenAI + domain | +26% recall improvement |
+| **Distributed SPARQL** | HDRF-partitioned Kubernetes clusters | 66-141ms across 3 executors |
+| **Auto-Embedding Triggers** | Vectors generated on graph insert/update | 37 µs incremental updates |
+
+```javascript
+const { GraphDB, Rdf2VecEngine, EmbeddingService } = require('rust-kgdb')
+```
+
+*See [Native Graph Embeddings](#native-graph-embeddings-rdf2vec-engine) for complete documentation and benchmarks.*
 
 ---
 
@@ -107,6 +124,26 @@ The math matters. When your fraud detection runs 35x faster, you catch fraud bef
 
 Most AI frameworks trust the LLM. We don't.
 
+### Core Capabilities
+
+| Layer | Feature | What It Does |
+|-------|---------|--------------|
+| **Database** | GraphDB | W3C SPARQL 1.1 compliant RDF store with 449ns lookups |
+| **Database** | Distributed SPARQL | HDRF partitioning across Kubernetes executors |
+| **Embeddings** | Rdf2VecEngine | Train 384-dim vectors from graph random walks |
+| **Embeddings** | EmbeddingService | Multi-provider composite vectors with RRF fusion |
+| **Embeddings** | HNSW Index | Approximate nearest neighbor search in 303µs |
+| **Analytics** | GraphFrames | PageRank, connected components, motif matching |
+| **Analytics** | Pregel API | Bulk synchronous parallel graph algorithms |
+| **Reasoning** | Datalog Engine | Recursive rule evaluation with fixpoint semantics |
+| **AI Agent** | HyperMindAgent | Schema-aware SPARQL generation from natural language |
+| **AI Agent** | Type System | Hindley-Milner type inference for query validation |
+| **AI Agent** | Proof DAG | SHA-256 audit trail for every AI decision |
+| **Security** | WASM Sandbox | Capability-based isolation with fuel metering |
+| **Security** | Schema Cache | Cross-agent ontology sharing with validation |
+
+### The Architecture Difference
+
 ```
 +===========================================================================+
 |                                                                           |
@@ -305,6 +342,97 @@ The difference? HyperMind treats tools as **typed morphisms** (category theory),
 
 ---
 
+## Native Graph Embeddings: RDF2Vec Engine
+
+Traditional embedding pipelines introduce significant latency: serialize your entity, make an HTTP request to OpenAI or Cohere, wait 200-500ms, parse the response. For applications requiring real-time similarity—fraud detection, recommendation engines, entity resolution—this latency model becomes a critical bottleneck.
+
+**RDF2Vec takes a fundamentally different approach.** Instead of treating entities as text to be embedded by external APIs, it learns vector representations directly from your graph's topology. The algorithm performs random walks across your knowledge graph, treating the resulting paths as "sentences" that capture structural relationships. These walks train a Word2Vec model in-process, producing embeddings that encode how entities relate to each other.
+
+```javascript
+const { GraphDB, Rdf2VecEngine } = require('rust-kgdb')
+
+// Load your knowledge graph
+const db = new GraphDB('http://enterprise/claims')
+db.loadTtl(claimsOntology, null)  // 130,923 triples/sec throughput
+
+// Initialize the RDF2Vec engine
+const rdf2vec = new Rdf2VecEngine()
+
+// Train embeddings from graph structure
+// Walks capture: Provider → submits → Claim → involves → Patient
+const walks = extractRandomWalks(db)
+rdf2vec.train(JSON.stringify(walks))  // 1,207 walks/sec → 384-dim vectors
+
+// Retrieve embeddings with microsecond latency
+const embedding = rdf2vec.getEmbedding('http://claims/provider/4521')  // 68 µs
+
+// Find structurally similar entities
+const similar = rdf2vec.findSimilar(provider, candidateProviders, 10)  // 303 µs
+```
+
+### Performance: Why Microseconds Matter
+
+| Operation | rust-kgdb (RDF2Vec) | External API (OpenAI) | Advantage |
+|-----------|---------------------|----------------------|-----------|
+| **Single Embedding Lookup** | 68 µs | 200-500 ms | **3,000-7,000x faster** |
+| **Similarity Search (k=10)** | 303 µs | 300-800 ms | **1,000-2,600x faster** |
+| **Batch Training (1K walks)** | 829 ms | N/A | Graph-native training |
+| **Rate Limits** | None (in-process) | Quota-restricted | Unlimited throughput |
+
+**Practical Impact**: When investigating a flagged claim, an analyst might check 50 similar providers. At 300ms per API call, that's 15 seconds of waiting. With RDF2Vec at 303µs per lookup, the same operation completes in 15 milliseconds—a 1,000x improvement that transforms the user experience from "waiting for AI" to "instant insight."
+
+### Multi-Vector Composite Embeddings with RRF
+
+Real-world similarity often requires multiple perspectives. A claim's structural relationships (RDF2Vec) tell a different story than its textual description (OpenAI) or domain-specific features (custom model). The `EmbeddingService` supports composite embeddings with Reciprocal Rank Fusion (RRF) to combine these views:
+
+```javascript
+const service = new EmbeddingService()
+
+// Store embeddings from multiple sources
+service.storeComposite('CLM-2024-0847', JSON.stringify({
+  rdf2vec: rdf2vec.getEmbedding('CLM-2024-0847'),   // Graph structure
+  openai: await openaiEmbed(claimNarrative),         // Semantic content
+  domain: fraudRiskEmbedding                         // Domain-specific signals
+}))
+
+// RRF fusion combines rankings from each source
+// Formula: Score = Σ(1 / (k + rank_i)), k=60
+const similar = service.findSimilarComposite('CLM-2024-0847', 10, 0.7, 'rrf')
+```
+
+| Candidate Pool | Single-Source Recall | RRF Composite Recall | Improvement |
+|----------------|---------------------|---------------------|-------------|
+| 100 entities | 78% | **89%** | +14% |
+| 1,000 entities | 72% | **85%** | +18% |
+| 10,000 entities | 65% | **82%** | +26% |
+
+### Distributed Cluster Benchmarks (Kubernetes)
+
+For deployments exceeding single-node capacity, rust-kgdb supports distributed execution across Kubernetes clusters. Verified benchmarks on the LUBM academic dataset:
+
+| Query | Pattern | Results | Latency |
+|-------|---------|---------|---------|
+| Q1 | Type lookup (GraduateStudent) | 150 | **66 ms** |
+| Q4 | Join (student → advisor) | 150 | **101 ms** |
+| Q6 | 2-hop join (advisor → department) | 46 | **75 ms** |
+| Q7 | Course enrollment scan | 570 | **141 ms** |
+
+**Configuration**: 1 coordinator + 3 executors, HDRF partitioning, NodePort access at `localhost:30080`. Triples distribute automatically across executors; multi-hop joins execute seamlessly across partition boundaries.
+
+### End-to-End Pipeline Throughput
+
+| Stage | Throughput | Notes |
+|-------|------------|-------|
+| Graph ingestion | **130,923 triples/sec** | Bulk load with indexing |
+| RDF2Vec training | **1,207 walks/sec** | Configurable walk length/count |
+| Embedding lookup | **68 µs** (14,700/sec) | In-memory, zero network |
+| Similarity search | **303 µs** (3,300/sec) | HNSW index |
+| Incremental update | **37 µs** | No full retrain required |
+
+*For detailed configuration options, see [Walk Configuration](#walk-configuration-tuning-rdf2vec-performance) and [Auto-Embedding Triggers](#auto-embedding-triggers-automatic-on-graph-insertupdate) below.*
+
+---
+
 ## The Deeper Problem: AI Agents Forget
 
 Fixing SPARQL syntax is table stakes. Here's what keeps enterprise architects up at night:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.6.78",
+  "version": "0.6.80",
   "description": "High-performance RDF/SPARQL database with AI agent framework. GraphDB (449ns lookups, 35x faster than RDFox), GraphFrames analytics (PageRank, motifs), Datalog reasoning, HNSW vector embeddings. HyperMindAgent for schema-aware query generation with audit trails. W3C SPARQL 1.1 compliant. Native performance via Rust + NAPI-RS.",
   "main": "index.js",
   "types": "index.d.ts",