rust-kgdb 0.6.48 → 0.6.50

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 +62 -0
  2. package/README.md +110 -16
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,68 @@
2
2
 
3
3
  All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
4
4
 
5
+ ## [0.6.50] - 2025-12-17
6
+
7
+ ### Complete Architecture Documentation
8
+
9
+ #### Comprehensive "What Is This?" Section
10
+ Added full architecture diagrams showing all implemented features:
11
+
12
+ **Layer 1: Rust Core (Native Performance)**
13
+ | Component | What It Does | Performance |
14
+ |-----------|--------------|-------------|
15
+ | SPARQL 1.1 | W3C-compliant, 64 builtins | 449ns lookups |
16
+ | WCOJ Joins | Worst-case optimal joins | O(N^(ρ/2)) |
17
+ | Datalog | Semi-naive evaluation | Incremental |
18
+ | Sparse Matrix | CSR/CSC reasoning (OWL 2 RL) | Memory-efficient |
19
+ | GraphFrames | PageRank, components, motifs | Parallel |
20
+ | Pregel | Bulk Synchronous Parallel | Superstep-based |
21
+ | HNSW | Hierarchical NSW index | O(log N) |
22
+ | ARCADE Cache | 1-hop neighbor pre-cache | O(1) context |
23
+ | Storage | InMemory/RocksDB/LMDB | 24 bytes/triple |
24
+
25
+ **Layer 2: HyperMind Agent Framework (JavaScript)**
26
+ | Component | What It Does |
27
+ |-----------|--------------|
28
+ | LLMPlanner | Schema-aware query generation |
29
+ | MemoryManager | Working + episodic + long-term memory |
30
+ | WASM Sandbox | Secure execution with capabilities |
31
+ | ProofDAG | Audit trail with hash |
32
+ | TypedTools | Input/output validation |
33
+
34
+ **New WASM Sandbox Diagram**: Shows capability-based security, fuel metering, and audit logging.
35
+
36
+ ---
37
+
38
+ ## [0.6.49] - 2025-12-17
39
+
40
+ ### Core Concepts Section Added
41
+
42
+ #### New "What We Bring and Why" Section
43
+ Simple Problem → Solution format explaining our 5 core innovations:
44
+
45
+ 1. **Schema-Aware Query Generation**
46
+ - Problem: LLMs hallucinate predicates
47
+ - Solution: Auto-extract schema, inject into prompts
48
+
49
+ 2. **Built-in Database (Not BYODB)**
50
+ - Problem: Other frameworks generate queries but need external DB
51
+ - Solution: rust-kgdb IS the database
52
+
53
+ 3. **Audit Trail (Provenance)**
54
+ - Problem: Where did that answer come from?
55
+ - Solution: Full reasoning trace with every answer
56
+
57
+ 4. **Deterministic Execution**
58
+ - Problem: Same question → different answers
59
+ - Solution: Same hash for same input (compliance-ready)
60
+
61
+ 5. **ARCADE 1-Hop Cache**
62
+ - Problem: Slow embedding neighborhood lookups
63
+ - Solution: Pre-cached 1-hop neighbors for O(1) context
64
+
65
+ ---
66
+
5
67
  ## [0.6.48] - 2025-12-17
6
68
 
7
69
  ### Clearer Product Definition
package/README.md CHANGED
@@ -6,22 +6,116 @@
6
6
 
7
7
  ## What Is This?
8
8
 
9
- **rust-kgdb** is two things in one package:
10
-
11
- 1. **High-Performance RDF Database** (Rust core)
12
- - SPARQL 1.1 query engine with 449ns lookup speed
13
- - GraphFrames analytics (PageRank, connected components, motifs)
14
- - Datalog reasoning engine
15
- - HNSW vector embeddings for similarity search
16
- - 35x faster than RDFox, 25% less memory
17
-
18
- 2. **HyperMind Agent Framework** (JavaScript layer)
19
- - AI agents that query the database using natural language
20
- - Schema auto-extraction from your data
21
- - Typed tools that prevent hallucination
22
- - Audit trail for every answer
23
-
24
- **Think of it as**: A knowledge graph database with an AI agent layer on top. The database provides ground truth. The agent layer makes it accessible via natural language.
9
+ **rust-kgdb** is two layers in one package:
10
+
11
+ ```
12
+ ┌─────────────────────────────────────────────────────────────────────────────┐
13
+ │ YOUR APPLICATION │
14
+ └─────────────────────────────────┬───────────────────────────────────────────┘
15
+ │
16
+ ┌─────────────────────────────────▼───────────────────────────────────────────┐
17
+ │ HYPERMIND AGENT FRAMEWORK (JavaScript) │
18
+ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
19
+ │ │ LLMPlanner │ │ MemoryMgr │ │ WASM │ │ ProofDAG │ │
20
+ │ │ (Schema- │ │ (Working/ │ │ Sandbox │ │ (Audit │ │
21
+ │ │ Aware) │ │ Episodic) │ │ (Secure) │ │ Trail) │ │
22
+ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
23
+ └─────────────────────────────────┬───────────────────────────────────────────┘
24
+ │ NAPI-RS (zero-copy)
25
+ ┌─────────────────────────────────▼───────────────────────────────────────────┐
26
+ │ RUST CORE (Native Performance) │
27
+ │ ┌──────────────────────────────────────────────────────────────────────┐ │
28
+ │ │ QUERY ENGINE │ │
29
+ │ │ • SPARQL 1.1 (449ns lookups) • WCOJ Joins (worst-case optimal) │ │
30
+ │ │ • Datalog (semi-naive eval) • Sparse Matrix (CSR/CSC reasoning) │ │
31
+ │ └──────────────────────────────────────────────────────────────────────┘ │
32
+ │ ┌──────────────────────────────────────────────────────────────────────┐ │
33
+ │ │ GRAPH ANALYTICS │ │
34
+ │ │ • GraphFrames (PageRank, Components, Triangles, Motifs) │ │
35
+ │ │ • Pregel BSP (Bulk Synchronous Parallel) │ │
36
+ │ │ • Shortest Paths, Label Propagation │ │
37
+ │ └──────────────────────────────────────────────────────────────────────┘ │
38
+ │ ┌──────────────────────────────────────────────────────────────────────┐ │
39
+ │ │ VECTOR & RETRIEVAL │ │
40
+ │ │ • HNSW Index (O(log N) ANN) • ARCADE 1-Hop Cache (O(1) neighbors) │ │
41
+ │ │ • Multi-provider Embeddings • RRF Reranking │ │
42
+ │ └──────────────────────────────────────────────────────────────────────┘ │
43
+ │ ┌──────────────────────────────────────────────────────────────────────┐ │
44
+ │ │ STORAGE │ │
45
+ │ │ • InMemory (dev) • RocksDB (prod) • LMDB (read-heavy) │ │
46
+ │ │ • SPOC/POCS/OCSP/CSPO Indexes • 24 bytes/triple │ │
47
+ │ └──────────────────────────────────────────────────────────────────────┘ │
48
+ └─────────────────────────────────────────────────────────────────────────────┘
49
+ ```
50
+
51
+ ### Layer 1: Rust Core (Native Performance)
52
+
53
+ | Component | What It Does | Performance |
54
+ |-----------|--------------|-------------|
55
+ | **SPARQL 1.1** | W3C-compliant query engine, 64 builtin functions | 449ns lookups |
56
+ | **WCOJ Joins** | Worst-case optimal joins for multi-way patterns | O(N^(ρ/2)) |
57
+ | **Datalog** | Semi-naive evaluation with recursion | Incremental |
58
+ | **Sparse Matrix** | CSR/CSC-based reasoning for OWL 2 RL | Memory-efficient |
59
+ | **GraphFrames** | PageRank, components, triangles, motifs | Parallel |
60
+ | **Pregel** | Bulk Synchronous Parallel graph processing | Superstep-based |
61
+ | **HNSW** | Hierarchical Navigable Small World index | O(log N) |
62
+ | **ARCADE Cache** | 1-hop neighbor pre-caching | O(1) context |
63
+ | **Storage** | InMemory, RocksDB, LMDB backends | 24 bytes/triple |
64
+
65
+ ### Layer 2: HyperMind Agent Framework (JavaScript)
66
+
67
+ | Component | What It Does |
68
+ |-----------|--------------|
69
+ | **LLMPlanner** | Schema-aware query generation (auto-extracts from data) |
70
+ | **MemoryManager** | Working memory + episodic memory + long-term KG |
71
+ | **WASM Sandbox** | Secure execution with capability-based permissions |
72
+ | **ProofDAG** | Audit trail with cryptographic hash for reproducibility |
73
+ | **TypedTools** | Input/output validation prevents hallucination |
74
+
75
+ ### WASM Sandbox Architecture
76
+
77
+ ```
78
+ ┌─────────────────────────────────────────────────────────────────────────────┐
79
+ │ WASM SANDBOX (Secure Agent Execution) │
80
+ ├─────────────────────────────────────────────────────────────────────────────┤
81
+ │ │
82
+ │ ┌─────────────────────┐ ┌─────────────────────┐ ┌────────────────┐ │
83
+ │ │ CAPABILITIES │ │ FUEL METERING │ │ AUDIT LOG │ │
84
+ │ │ • ReadKG │ │ • CPU budget limit │ │ • Every action │ │
85
+ │ │ • ExecuteTool │ │ • Prevents infinite │ │ • Timestamps │ │
86
+ │ │ • WriteKG (opt) │ │ loops │ │ • Arguments │ │
87
+ │ └─────────────────────┘ └─────────────────────┘ └────────────────┘ │
88
+ │ │
89
+ │ Agent Code → WASM Runtime → Capability Check → Tool Execution → Audit │
90
+ │ │
91
+ └─────────────────────────────────────────────────────────────────────────────┘
92
+ ```
93
+
94
+ **Think of it as**: A knowledge graph database (Rust, native performance) with an AI agent runtime (JavaScript, WASM-sandboxed) on top. The database provides ground truth. The runtime makes it accessible via natural language with full security and audit trails.
95
+
96
+ ---
97
+
98
+ ## Core Concepts: What We Bring and Why
99
+
100
+ ### 1. Schema-Aware Query Generation
101
+ **Problem**: LLMs generate SPARQL with made-up predicates (`?person :fakeProperty ?value`).
102
+ **Solution**: We auto-extract your schema and inject it into prompts. The LLM can ONLY reference predicates that actually exist in your data.
103
+
104
+ ### 2. Built-in Database (Not BYODB)
105
+ **Problem**: LangChain/DSPy generate queries, but you need to find a database to run them.
106
+ **Solution**: rust-kgdb IS the database. Generate query → Execute query → Return results. All in one package.
107
+
108
+ ### 3. Audit Trail (Provenance)
109
+ **Problem**: LLM says "Provider P001 is suspicious" - where did that come from?
110
+ **Solution**: Every answer includes a reasoning trace showing which SPARQL queries ran, which rules matched, and what data was found.
111
+
112
+ ### 4. Deterministic Execution
113
+ **Problem**: Ask the same question twice, get different answers.
114
+ **Solution**: Same input → Same query → Same database → Same result → Same hash. Reproducible for compliance.
115
+
116
+ ### 5. ARCADE 1-Hop Cache
117
+ **Problem**: Embedding lookups are slow when you need neighborhood context.
118
+ **Solution**: Pre-cache 1-hop neighbors. When you find "Provider", instantly know its outgoing predicates (hasRiskScore, hasClaim) without another query.
25
119
 
26
120
  ---
27
121
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rust-kgdb",
3
- "version": "0.6.48",
3
+ "version": "0.6.50",
4
4
  "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.",
5
5
  "main": "index.js",
6
6
  "types": "index.d.ts",