rust-kgdb 0.6.23 → 0.6.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +232 -2
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,44 @@
2
2
 
3
3
  All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
4
4
 
5
+ ## [0.6.24] - 2025-12-16
6
+
7
+ ### Comprehensive Technical Documentation
8
+
9
+ Complete feature documentation with factual accuracy verified against codebase.
10
+
11
+ #### Competitive Landscape Updates
12
+ - **Tentris comparison**: WCOJ-optimized triplestore with ISWC 2025 paper reference
13
+ - **AllegroGraph comparison**: Enterprise features, slower than rust-kgdb
14
+ - **Triple stores table**: 9 systems compared on lookup speed, memory, WCOJ, mobile, AI
15
+
16
+ #### New Feature Tables
17
+ - **WCOJ (Worst-Case Optimal Joins)**: O(N^(ρ/2)) complexity, multi-way joins, adaptive plans
18
+ - **Ontology & Reasoning**: RDFS, OWL 2 RL (7 rules), SHACL validation
19
+ - **Distribution**: HDRF partitioning, Raft consensus, gRPC, Kubernetes-native
20
+ - **Storage Backends**: InMemory, RocksDB, LMDB with use cases
21
+ - **Mobile Support**: iOS (Swift), Android (Kotlin), Node.js, Python
22
+
23
+ #### Complete Feature Overview Table
24
+ 17 features organized by category (Core, Analytics, AI, Reasoning, Ontology, Joins, Distribution, Mobile, Storage)
25
+
26
+ #### Comprehensive Example Tables
27
+ - **SPARQL Examples**: 16 query types with examples
28
+ - **Datalog Examples**: 6 inference patterns
29
+ - **Motif Pattern Syntax**: 7 pattern types with syntax
30
+ - **GraphFrame Algorithms**: 8 algorithms with methods and outputs
31
+ - **Embedding Operations**: 6 operations
32
+
33
+ #### Distributed Deployment Section
34
+ - Architecture diagram (Coordinator + Executors)
35
+ - Helm deployment commands
36
+ - Key distributed features table (HDRF, Raft, gRPC, Shadow Partitions, DataFusion)
37
+
38
+ #### Pregel Example
39
+ BSP graph processing with chainGraph and pregelShortestPaths
40
+
41
+ ---
42
+
5
43
  ## [0.6.23] - 2025-12-16
6
44
 
7
45
  ### Restored Technical Depth: Full Documentation
package/README.md CHANGED
@@ -240,6 +240,69 @@ const result = await agent.call('Calculate risk score for entity P001')
240
240
  | **Bulk Insert** | 146K triples/sec | Production-grade |
241
241
  | **Memory** | 24 bytes/triple | Best-in-class efficiency |
242
242
 
243
+ ### Join Optimization (WCOJ)
244
+ | Feature | Description |
245
+ |---------|-------------|
246
+ | **WCOJ Algorithm** | Worst-case optimal joins with O(N^(ρ/2)) complexity |
247
+ | **Multi-way Joins** | Process multiple patterns simultaneously |
248
+ | **Adaptive Plans** | Cost-based optimizer selects best strategy |
249
+
250
+ **Research Foundation**: WCOJ algorithms are the state-of-the-art for graph pattern matching. See [Tentris WCOJ Update (ISWC 2025)](https://papers.dice-research.org/2025/ISWC_Tentris-WCOJ-Update/public.pdf) for latest research.
251
+
252
+ ### Ontology & Reasoning
253
+ | Feature | Description |
254
+ |---------|-------------|
255
+ | **RDFS Reasoner** | Subclass/subproperty inference |
256
+ | **OWL 2 RL** | Rule-based OWL reasoning (prp-dom, prp-rng, prp-symp, prp-trp, cls-hv, cls-svf, cax-sco) |
257
+ | **SHACL** | W3C shapes constraint validation |
258
+
259
+ ### Distribution (Clustered Mode)
260
+ | Feature | Description |
261
+ |---------|-------------|
262
+ | **HDRF Partitioning** | Streaming graph partitioning (subject-anchored) |
263
+ | **Raft Consensus** | Distributed coordination |
264
+ | **gRPC** | Inter-node communication |
265
+ | **Kubernetes-Native** | Helm charts, health checks |
266
+
267
+ ### Storage Backends
268
+ | Backend | Use Case |
269
+ |---------|----------|
270
+ | **InMemory** | Development, testing, small datasets |
271
+ | **RocksDB** | Production, large datasets, ACID |
272
+ | **LMDB** | Read-heavy workloads, memory-mapped |
273
+
274
+ ### Mobile Support
275
+ | Platform | Binding |
276
+ |----------|---------|
277
+ | **iOS** | Swift via UniFFI 0.30 |
278
+ | **Android** | Kotlin via UniFFI 0.30 |
279
+ | **Node.js** | NAPI-RS (this package) |
280
+ | **Python** | UniFFI (separate package) |
281
+
282
+ ---
283
+
284
+ ## Complete Feature Overview
285
+
286
+ | Category | Feature | What It Does |
287
+ |----------|---------|--------------|
288
+ | **Core** | GraphDB | High-performance RDF/SPARQL quad store |
289
+ | **Core** | SPOC Indexes | Four-way indexing (SPOC/POCS/OCSP/CSPO) |
290
+ | **Core** | Dictionary | String interning with 8-byte IDs |
291
+ | **Analytics** | GraphFrames | PageRank, connected components, triangles |
292
+ | **Analytics** | Motif Finding | Pattern matching DSL |
293
+ | **Analytics** | Pregel | BSP parallel graph processing |
294
+ | **AI** | Embeddings | HNSW similarity with 1-hop ARCADE cache |
295
+ | **AI** | HyperMind | Neuro-symbolic agent framework |
296
+ | **Reasoning** | Datalog | Semi-naive evaluation engine |
297
+ | **Reasoning** | RDFS Reasoner | Subclass/subproperty inference |
298
+ | **Reasoning** | OWL 2 RL | Rule-based OWL reasoning |
299
+ | **Ontology** | SHACL | W3C shapes constraint validation |
300
+ | **Joins** | WCOJ | Worst-case optimal join algorithm |
301
+ | **Distribution** | HDRF | Streaming graph partitioning |
302
+ | **Distribution** | Raft | Consensus for coordination |
303
+ | **Mobile** | iOS/Android | Swift and Kotlin bindings via UniFFI |
304
+ | **Storage** | InMemory/RocksDB/LMDB | Three backend options |
305
+
243
306
  ---
244
307
 
245
308
  ## How It Works
@@ -503,6 +566,93 @@ const similar = JSON.parse(embeddings.findSimilar('claim_001', 5, 0.7))
503
566
  console.log('Similar:', similar)
504
567
  ```
505
568
 
569
+ ### Pregel (BSP Graph Processing)
570
+
571
+ ```javascript
572
+ const { chainGraph, pregelShortestPaths } = require('rust-kgdb')
573
+
574
+ // Create a chain: v0 -> v1 -> v2 -> v3 -> v4
575
+ const graph = chainGraph(5)
576
+
577
+ // Compute shortest paths from v0
578
+ const result = JSON.parse(pregelShortestPaths(graph, 'v0', 10))
579
+ console.log('Distances:', result.distances)
580
+ // { v0: 0, v1: 1, v2: 2, v3: 3, v4: 4 }
581
+ console.log('Supersteps:', result.supersteps) // 5
582
+ ```
583
+
584
+ ---
585
+
586
+ ## Comprehensive Example Tables
587
+
588
+ ### SPARQL Examples
589
+
590
+ | Query Type | Example | Description |
591
+ |------------|---------|-------------|
592
+ | **SELECT** | `SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10` | Basic triple pattern |
593
+ | **FILTER** | `SELECT ?p WHERE { ?p :age ?a . FILTER(?a > 30) }` | Numeric filtering |
594
+ | **OPTIONAL** | `SELECT ?p ?email WHERE { ?p a :Person . OPTIONAL { ?p :email ?email } }` | Left outer join |
595
+ | **UNION** | `SELECT ?x WHERE { { ?x a :Cat } UNION { ?x a :Dog } }` | Pattern union |
596
+ | **CONSTRUCT** | `CONSTRUCT { ?s :knows ?o } WHERE { ?s :friend ?o }` | Create new triples |
597
+ | **ASK** | `ASK WHERE { :alice :knows :bob }` | Boolean existence check |
598
+ | **INSERT** | `INSERT DATA { :alice :knows :charlie }` | Add triples |
599
+ | **DELETE** | `DELETE WHERE { :alice :knows ?anyone }` | Remove triples |
600
+ | **Aggregation** | `SELECT (COUNT(?p) AS ?cnt) WHERE { ?p a :Person }` | Count/Sum/Avg/Min/Max |
601
+ | **GROUP BY** | `SELECT ?dept (COUNT(?e) AS ?cnt) WHERE { ?e :worksIn ?dept } GROUP BY ?dept` | Grouping |
602
+ | **HAVING** | `SELECT ?dept (COUNT(?e) AS ?cnt) WHERE { ?e :worksIn ?dept } GROUP BY ?dept HAVING (COUNT(?e) > 5)` | Filter groups |
603
+ | **ORDER BY** | `SELECT ?p ?age WHERE { ?p :age ?age } ORDER BY DESC(?age)` | Sorting |
604
+ | **DISTINCT** | `SELECT DISTINCT ?type WHERE { ?s a ?type }` | Remove duplicates |
605
+ | **VALUES** | `SELECT ?p WHERE { VALUES ?type { :Cat :Dog } ?p a ?type }` | Inline data |
606
+ | **BIND** | `SELECT ?p ?label WHERE { ?p :name ?n . BIND(CONCAT("Mr. ", ?n) AS ?label) }` | Computed values |
607
+ | **Subquery** | `SELECT ?p WHERE { { SELECT ?p WHERE { ?p :score ?s } ORDER BY DESC(?s) LIMIT 10 } }` | Nested queries |
608
+
609
+ ### Datalog Examples
610
+
611
+ | Pattern | Rule | Description |
612
+ |---------|------|-------------|
613
+ | **Transitive Closure** | `ancestor(?X,?Z) :- parent(?X,?Y), ancestor(?Y,?Z)` | Recursive ancestor |
614
+ | **Symmetric** | `knows(?X,?Y) :- knows(?Y,?X)` | Bidirectional relations |
615
+ | **Composition** | `grandparent(?X,?Z) :- parent(?X,?Y), parent(?Y,?Z)` | Two-hop relation |
616
+ | **Negation** | `lonely(?X) :- person(?X), NOT friend(?X,?Y)` | Absence check |
617
+ | **Aggregation** | `popular(?X) :- friend(?X,?Y), COUNT(?Y) > 10` | Count-based rules |
618
+ | **Path Finding** | `reachable(?X,?Y) :- edge(?X,?Y). reachable(?X,?Z) :- edge(?X,?Y), reachable(?Y,?Z)` | Graph connectivity |
619
+
620
+ ### Motif Pattern Syntax
621
+
622
+ | Pattern | Syntax | Matches |
623
+ |---------|--------|---------|
624
+ | **Single Edge** | `(a)-[]->(b)` | All directed edges |
625
+ | **Two-Hop** | `(a)-[]->(b); (b)-[]->(c)` | Paths of length 2 |
626
+ | **Triangle** | `(a)-[]->(b); (b)-[]->(c); (c)-[]->(a)` | Closed triangles |
627
+ | **Star** | `(center)-[]->(a); (center)-[]->(b); (center)-[]->(c)` | Hub patterns |
628
+ | **Named Edge** | `(a)-[e]->(b)` | Capture edge in variable `e` |
629
+ | **Negation** | `(a)-[]->(b); !(b)-[]->(a)` | One-way edges only |
630
+ | **Diamond** | `(a)-[]->(b); (a)-[]->(c); (b)-[]->(d); (c)-[]->(d)` | Diamond pattern |
631
+
632
+ ### GraphFrame Algorithms
633
+
634
+ | Algorithm | Method | Input | Output |
635
+ |-----------|--------|-------|--------|
636
+ | **PageRank** | `graph.pageRank(0.15, 20)` | damping, iterations | `{ ranks: {id: score}, iterations, converged }` |
637
+ | **Connected Components** | `graph.connectedComponents()` | - | `{ components: {id: componentId}, count }` |
638
+ | **Shortest Paths** | `graph.shortestPaths(['v0', 'v5'])` | landmark vertices | `{ distances: {id: {landmark: dist}} }` |
639
+ | **Label Propagation** | `graph.labelPropagation(10)` | max iterations | `{ labels: {id: label}, iterations }` |
640
+ | **Triangle Count** | `graph.triangleCount()` | - | Number of triangles |
641
+ | **Motif Finding** | `graph.find('(a)-[]->(b)')` | pattern string | Array of matches |
642
+ | **Degrees** | `graph.degrees()` / `inDegrees()` / `outDegrees()` | - | `{ id: degree }` |
643
+ | **Pregel** | `pregelShortestPaths(graph, 'v0', 10)` | landmark, maxSteps | `{ distances, supersteps }` |
644
+
645
+ ### Embedding Operations
646
+
647
+ | Operation | Method | Description |
648
+ |-----------|--------|-------------|
649
+ | **Store Vector** | `service.storeVector('id', [0.1, 0.2, ...])` | Store 384-dim embedding |
650
+ | **Find Similar** | `service.findSimilar('id', 10, 0.7)` | HNSW k-NN search |
651
+ | **Composite Store** | `service.storeComposite('id', JSON.stringify({openai: [...], voyage: [...]}))` | Multi-provider |
652
+ | **Composite Search** | `service.findSimilarComposite('id', 10, 0.7, 'rrf')` | RRF/max/voting aggregation |
653
+ | **1-Hop Cache** | `service.getNeighborsOut('id')` / `getNeighborsIn('id')` | ARCADE neighbor cache |
654
+ | **Rebuild Index** | `service.rebuildIndex()` | Rebuild HNSW index |
655
+
506
656
  ---
507
657
 
508
658
  ## Benchmarks
@@ -678,6 +828,57 @@ const agent = new HyperMindAgent({
678
828
  })
679
829
  ```
680
830
 
831
+ ### Distributed Deployment (Kubernetes)
832
+
833
+ rust-kgdb scales from single-node to distributed cluster on the same codebase.
834
+
835
+ ```
836
+ ┌─────────────────────────────────────────────────────────────────────────────┐
837
+ │ DISTRIBUTED ARCHITECTURE │
838
+ │ │
839
+ │ ┌─────────────────────────────────────────────────────────────────────┐ │
840
+ │ │ COORDINATOR NODE │ │
841
+ │ │ • Query planning & optimization │ │
842
+ │ │ • HDRF streaming partitioner (subject-anchored) │ │
843
+ │ │ • Raft consensus leader │ │
844
+ │ │ • gRPC routing to executors │ │
845
+ │ └──────────────────────────────┬──────────────────────────────────────┘ │
846
+ │ │ │
847
+ │ ┌───────────────────────┼───────────────────────┐ │
848
+ │ │ │ │ │
849
+ │ ▼ ▼ ▼ │
850
+ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
851
+ │ │ EXECUTOR 1 │ │ EXECUTOR 2 │ │ EXECUTOR 3 │ │
852
+ │ │ │ │ │ │ │ │
853
+ │ │ Partition 0 │ │ Partition 1 │ │ Partition 2 │ │
854
+ │ │ RocksDB │ │ RocksDB │ │ RocksDB │ │
855
+ │ │ Embeddings │ │ Embeddings │ │ Embeddings │ │
856
+ │ └─────────────┘ └─────────────┘ └─────────────┘ │
857
+ │ │
858
+ └─────────────────────────────────────────────────────────────────────────────┘
859
+ ```
860
+
861
+ **Deployment with Helm:**
862
+ ```bash
863
+ # Deploy to Kubernetes
864
+ helm install rust-kgdb ./infra/helm -n rust-kgdb --create-namespace
865
+
866
+ # Scale executors
867
+ kubectl scale deployment rust-kgdb-executor --replicas=5 -n rust-kgdb
868
+
869
+ # Check cluster health
870
+ kubectl get pods -n rust-kgdb
871
+ ```
872
+
873
+ **Key Distributed Features:**
874
+ | Feature | Description |
875
+ |---------|-------------|
876
+ | **HDRF Partitioning** | Subject-anchored streaming partitioner minimizes edge cuts |
877
+ | **Raft Consensus** | Leader election, log replication, consistency |
878
+ | **gRPC Communication** | Efficient inter-node query routing |
879
+ | **Shadow Partitions** | Zero-downtime rebalancing (~10ms pause) |
880
+ | **DataFusion OLAP** | Arrow-native analytical queries |
881
+
681
882
  ### Memory System
682
883
 
683
884
  Agents have persistent memory across sessions:
@@ -1001,19 +1202,48 @@ Result: ❌ PARSER ERROR - Invalid SPARQL syntax
1001
1202
 
1002
1203
  ### Competitive Landscape
1003
1204
 
1205
+ #### Triple Stores Comparison
1206
+
1207
+ | System | Lookup Speed | Memory/Triple | WCOJ | Mobile | AI Framework |
1208
+ |--------|-------------|---------------|------|--------|--------------|
1209
+ | **rust-kgdb** | **2.78 µs** | **24 bytes** | ✅ Yes | ✅ Yes | ✅ HyperMind |
1210
+ | Tentris | ~5 µs | ~30 bytes | ✅ Yes | ❌ No | ❌ No |
1211
+ | RDFox | ~5 µs | 36-89 bytes | ❌ No | ❌ No | ❌ No |
1212
+ | AllegroGraph | ~10 µs | 50+ bytes | ❌ No | ❌ No | ❌ No |
1213
+ | Virtuoso | ~5 µs | 35-75 bytes | ❌ No | ❌ No | ❌ No |
1214
+ | Blazegraph | ~100 µs | 100+ bytes | ❌ No | ❌ No | ❌ No |
1215
+ | Apache Jena | 150+ µs | 50-60 bytes | ❌ No | ❌ No | ❌ No |
1216
+ | Neo4j | ~5 µs | 70+ bytes | ❌ No | ❌ No | ❌ No |
1217
+ | Amazon Neptune | ~5 µs | N/A (managed) | ❌ No | ❌ No | ❌ No |
1218
+
1219
+ **Note**: Tentris implements WCOJ (see [ISWC 2025 paper](https://papers.dice-research.org/2025/ISWC_Tentris-WCOJ-Update/public.pdf)). rust-kgdb is the only system combining WCOJ with mobile support and integrated AI framework.
1220
+
1221
+ #### AI Framework Comparison
1222
+
1223
+ | Framework | Type Safety | Schema Aware | Symbolic Execution | Audit Trail | Success Rate |
1224
+ |-----------|-------------|--------------|-------------------|-------------|--------------|
1225
+ | **HyperMind** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | **86.4%** |
1226
+ | LangChain | ❌ No | ❌ No | ❌ No | ❌ No | ~20-40%* |
1227
+ | AutoGPT | ❌ No | ❌ No | ❌ No | ❌ No | ~10-25%* |
1228
+ | DSPy | ⚠️ Partial | ❌ No | ❌ No | ❌ No | ~30-50%* |
1229
+
1230
+ *Estimated from public benchmarks on structured data tasks
1231
+
1004
1232
  ```
1005
1233
  ┌─────────────────────────────────────────────────────────────────┐
1006
1234
  │ COMPETITIVE LANDSCAPE │
1007
1235
  ├─────────────────────────────────────────────────────────────────┤
1008
1236
  │ │
1237
+ │ Tentris: WCOJ-optimized, but no mobile or AI framework │
1238
+ │ RDFox: Fast commercial, but expensive, no mobile │
1239
+ │ AllegroGraph: Enterprise features, but slower, no mobile │
1009
1240
  │ Apache Jena: Great features, but 150+ µs lookups │
1010
- │ RDFox: Fast, but expensive and no mobile support │
1011
1241
  │ Neo4j: Popular, but no SPARQL/RDF standards │
1012
1242
  │ Amazon Neptune: Managed, but cloud-only vendor lock-in │
1013
1243
  │ LangChain: Vibe coding, fails compliance audits │
1014
1244
  │ DSPy: Statistical optimization, no guarantees │
1015
1245
  │ │
1016
- │ rust-kgdb: 2.78 µs lookups, mobile-native, open standards │
1246
+ │ rust-kgdb: 2.78 µs lookups, WCOJ joins, mobile-native │
1017
1247
  │ Standalone → Clustered on same codebase │
1018
1248
  │ Mathematical foundations, audit-ready │
1019
1249
  │ │
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rust-kgdb",
3
- "version": "0.6.23",
3
+ "version": "0.6.24",
4
4
  "description": "Production-grade Neuro-Symbolic AI Framework with Schema-Aware GraphDB, Context Theory, and Memory Hypergraph: +86.4% accuracy over vanilla LLMs. Features Schema-Aware GraphDB (auto schema extraction), BYOO (Bring Your Own Ontology) for enterprise, cross-agent schema caching, LLM Planner for natural language to typed SPARQL, ProofDAG with Curry-Howard witnesses. High-performance (2.78µs lookups, 35x faster than RDFox). W3C SPARQL 1.1 compliant.",
5
5
  "main": "index.js",
6
6
  "types": "index.d.ts",