rust-kgdb 0.6.72 → 0.6.74
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.
- package/CHANGELOG.md +32 -0
- package/DESIGN.md +34 -34
- package/IMPLEMENTATION_GUIDE.md +35 -35
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,38 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [0.6.72] - 2025-12-17
|
|
6
|
+
|
|
7
|
+
### Comprehensive Documentation Overhaul
|
|
8
|
+
|
|
9
|
+
#### Added Human-Style SME Introduction
|
|
10
|
+
- **"The Problem With AI Today"** - Real-world hallucination examples (Provider #4521, fake court cases, Nexapril)
|
|
11
|
+
- **"The Engineering Problem"** - Root cause analysis: LLMs predict text, not facts
|
|
12
|
+
- **"The Solution: Query Generation, Not Answer Generation"** - Key architectural insight
|
|
13
|
+
- **"The Business Value"** - Metrics for Enterprises, Engineering Teams, AI/ML Teams
|
|
14
|
+
|
|
15
|
+
#### Added Three-Box Architecture Diagram
|
|
16
|
+
- Traditional AI Architecture (Dangerous) - Shows LLM generating fabricated answers
|
|
17
|
+
- rust-kgdb + HyperMind Architecture (Safe) - Shows query generation with verification
|
|
18
|
+
- Four-Layer Trust Model - Agent -> Proxy -> Sandbox -> Database
|
|
19
|
+
|
|
20
|
+
#### Added Honest Competitor Comparison
|
|
21
|
+
- **RDFox**: Oxford Semantic Technologies (35x slower on lookups, but more mature OWL)
|
|
22
|
+
- **Tentris**: DICE Research tensor-based WCOJ (similar performance, different approach)
|
|
23
|
+
- **AllegroGraph**: Franz Inc (25+ years track record, enterprise integrations)
|
|
24
|
+
- **Apache Jena**: Apache Foundation (largest ecosystem, best community)
|
|
25
|
+
|
|
26
|
+
#### Added WCOJ Research Section
|
|
27
|
+
- Comparison table: rust-kgdb vs RDFox vs Tentris vs Jena
|
|
28
|
+
- Research paper links (Veldhuizen 2014, DICE 2025, AGM Bound)
|
|
29
|
+
- Triangle query complexity example (10^18 vs 10^9)
|
|
30
|
+
|
|
31
|
+
#### Fixed npm README Display
|
|
32
|
+
- Converted Unicode box-drawing characters to ASCII
|
|
33
|
+
- README now displays correctly on npmjs.com
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
5
37
|
## [0.6.55] - 2025-12-17
|
|
6
38
|
|
|
7
39
|
### Thought-Provoking Documentation Rewrite
|
package/DESIGN.md
CHANGED
|
@@ -5,28 +5,28 @@
|
|
|
5
5
|
HyperMind is a neuro-symbolic AI framework that combines LLM planning with deterministic database execution. Unlike traditional AI agents that rely entirely on LLM outputs, HyperMind uses the LLM as a **planner** while executing queries against real data.
|
|
6
6
|
|
|
7
7
|
```
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
8
|
+
+-----------------------------------------------------------------------------+
|
|
9
|
+
| HYPERMIND ARCHITECTURE |
|
|
10
|
+
+-----------------------------------------------------------------------------+
|
|
11
|
+
| |
|
|
12
|
+
| +-------------+ +-------------+ +-------------+ +-------------+ |
|
|
13
|
+
| | User | | Schema | | LLM | | Typed | |
|
|
14
|
+
| | Query | -> | Context | -> | Planner | -> | Tools | |
|
|
15
|
+
| +-------------+ +-------------+ +-------------+ +-------------+ |
|
|
16
|
+
| | | |
|
|
17
|
+
| | v |
|
|
18
|
+
| | +-------------+ |
|
|
19
|
+
| | | Database | |
|
|
20
|
+
| | | Execution | |
|
|
21
|
+
| | +-------------+ |
|
|
22
|
+
| | | |
|
|
23
|
+
| v v |
|
|
24
|
+
| +-------------------------------------------------+ |
|
|
25
|
+
| | Reasoning Trace | |
|
|
26
|
+
| | (Every step recorded with cryptographic hash) | |
|
|
27
|
+
| +-------------------------------------------------+ |
|
|
28
|
+
| |
|
|
29
|
+
+-----------------------------------------------------------------------------+
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
---
|
|
@@ -62,7 +62,7 @@ When LLM generates incorrect predicates, the resolver fixes them:
|
|
|
62
62
|
|
|
63
63
|
```
|
|
64
64
|
LLM Output: SELECT ?x WHERE { ?x teacher ?y }
|
|
65
|
-
|
|
65
|
+
^
|
|
66
66
|
Wrong predicate!
|
|
67
67
|
|
|
68
68
|
Resolver Process:
|
|
@@ -73,14 +73,14 @@ Resolver Process:
|
|
|
73
73
|
- Jaro-Winkler("teacher", "teacherOf") = 0.89
|
|
74
74
|
- N-gram overlap = 0.75
|
|
75
75
|
- Porter stem match = true
|
|
76
|
-
5. Resolve: "teacher"
|
|
76
|
+
5. Resolve: "teacher" -> "teacherOf"
|
|
77
77
|
|
|
78
78
|
Fixed Output: SELECT ?x WHERE { ?x teacherOf ?y }
|
|
79
|
-
|
|
79
|
+
^
|
|
80
80
|
Correct predicate!
|
|
81
81
|
```
|
|
82
82
|
|
|
83
|
-
**Benchmark result:** This adds +14.3 percentage points accuracy (71.4%
|
|
83
|
+
**Benchmark result:** This adds +14.3 percentage points accuracy (71.4% -> 85.7%)
|
|
84
84
|
|
|
85
85
|
### 3. Typed Tool Registry
|
|
86
86
|
|
|
@@ -139,12 +139,12 @@ Every answer includes a complete derivation:
|
|
|
139
139
|
Schema represented as a category:
|
|
140
140
|
- **Objects** = Classes (Professor, Course, Student)
|
|
141
141
|
- **Morphisms** = Properties (teacherOf, enrolledIn)
|
|
142
|
-
- **Composition** = Property paths (Professor
|
|
142
|
+
- **Composition** = Property paths (Professor -> Course -> Department)
|
|
143
143
|
|
|
144
144
|
```
|
|
145
|
-
Professor
|
|
146
|
-
|
|
147
|
-
|
|
145
|
+
Professor --teacherOf--> Course --offeredBy--> Department
|
|
146
|
+
| |
|
|
147
|
+
+------------worksFor--------------------------+
|
|
148
148
|
```
|
|
149
149
|
|
|
150
150
|
### Metric Space Similarity
|
|
@@ -171,7 +171,7 @@ Proofs are programs, types are propositions:
|
|
|
171
171
|
```
|
|
172
172
|
Query : SPARQLQuery (type = proposition)
|
|
173
173
|
Result : BindingSet (type = proposition)
|
|
174
|
-
Execution : Query
|
|
174
|
+
Execution : Query -> Result (proof = program)
|
|
175
175
|
|
|
176
176
|
The reasoning trace IS the proof that the answer is correct.
|
|
177
177
|
```
|
|
@@ -221,7 +221,7 @@ TEST_QUERIES = [
|
|
|
221
221
|
### LangChain
|
|
222
222
|
|
|
223
223
|
```
|
|
224
|
-
Architecture: Prompt Template
|
|
224
|
+
Architecture: Prompt Template -> LLM -> Text Output
|
|
225
225
|
Execution: None (LLM output is final answer)
|
|
226
226
|
Validation: None
|
|
227
227
|
Audit Trail: None
|
|
@@ -230,7 +230,7 @@ Audit Trail: None
|
|
|
230
230
|
### DSPy
|
|
231
231
|
|
|
232
232
|
```
|
|
233
|
-
Architecture: Signature
|
|
233
|
+
Architecture: Signature -> LLM -> Structured Output
|
|
234
234
|
Execution: None (LLM output is final answer)
|
|
235
235
|
Validation: Output structure only
|
|
236
236
|
Audit Trail: None
|
|
@@ -239,7 +239,7 @@ Audit Trail: None
|
|
|
239
239
|
### HyperMind
|
|
240
240
|
|
|
241
241
|
```
|
|
242
|
-
Architecture: Schema
|
|
242
|
+
Architecture: Schema -> LLM Planner -> Typed Tools -> Database -> Verified Answer
|
|
243
243
|
Execution: Real SPARQL/Datalog on actual data
|
|
244
244
|
Validation: Schema + Type + Predicate resolution
|
|
245
245
|
Audit Trail: Full reasoning trace with hash
|
package/IMPLEMENTATION_GUIDE.md
CHANGED
|
@@ -18,34 +18,34 @@
|
|
|
18
18
|
The TypeScript SDK uses **NAPI-RS** for native Rust bindings with zero-copy performance. Version 0.6.17 includes the complete HyperMind AI framework for building agents that give verifiable answers.
|
|
19
19
|
|
|
20
20
|
```
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
21
|
+
+-----------------------------------------------------------------------------+
|
|
22
|
+
| ARCHITECTURE OVERVIEW |
|
|
23
|
+
| |
|
|
24
|
+
| YOUR APPLICATION (Node.js / TypeScript) |
|
|
25
|
+
| | |
|
|
26
|
+
| v |
|
|
27
|
+
| +-----------------------------------------------------------------------+ |
|
|
28
|
+
| | index.js - Entry Point | |
|
|
29
|
+
| | * Platform detection (darwin/linux/win32 × x64/arm64) | |
|
|
30
|
+
| | * Native binding loader | |
|
|
31
|
+
| | * HyperMind framework exports | |
|
|
32
|
+
| +-----------------------------------------------------------------------+ |
|
|
33
|
+
| | | |
|
|
34
|
+
| v v |
|
|
35
|
+
| +---------------------+ +-----------------------------------------+ |
|
|
36
|
+
| | Native NAPI-RS | | hypermind-agent.js | |
|
|
37
|
+
| | (Rust -> Node.js) | | (Pure JavaScript Framework) | |
|
|
38
|
+
| | | | | |
|
|
39
|
+
| | * GraphDb | | * HyperMindAgent | |
|
|
40
|
+
| | * GraphFrame | | * LLMPlanner | |
|
|
41
|
+
| | * EmbeddingService | | * SchemaAwareGraphDB | |
|
|
42
|
+
| | * DatalogProgram | | * SchemaContext | |
|
|
43
|
+
| | * pregelShortestPaths| | * MemoryManager | |
|
|
44
|
+
| | | | * WasmSandbox | |
|
|
45
|
+
| | ~47MB native addon | | * ProofDAG | |
|
|
46
|
+
| +---------------------+ +-----------------------------------------+ |
|
|
47
|
+
| |
|
|
48
|
+
+-----------------------------------------------------------------------------+
|
|
49
49
|
```
|
|
50
50
|
|
|
51
51
|
## Core Components
|
|
@@ -184,7 +184,7 @@ The SDK automatically extracts your data structure:
|
|
|
184
184
|
class SchemaContext {
|
|
185
185
|
constructor() {
|
|
186
186
|
this.classes = new Set() // Objects in category
|
|
187
|
-
this.properties = new Map() // Morphisms: predicate
|
|
187
|
+
this.properties = new Map() // Morphisms: predicate -> {domain, range}
|
|
188
188
|
}
|
|
189
189
|
|
|
190
190
|
// Functor: Transform between schemas
|
|
@@ -342,12 +342,12 @@ npm run test:jest
|
|
|
342
342
|
|
|
343
343
|
```
|
|
344
344
|
tests/
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
345
|
+
+-- regression.test.ts # Core GraphDB tests (28 tests)
|
|
346
|
+
+-- graphframes.test.ts # GraphFrame tests
|
|
347
|
+
+-- embeddings.test.ts # EmbeddingService tests
|
|
348
|
+
+-- datalog.test.ts # Datalog tests
|
|
349
|
+
+-- pregel.test.ts # Pregel tests
|
|
350
|
+
+-- hypermind-agent.test.ts # HyperMind framework tests (59 tests)
|
|
351
351
|
```
|
|
352
352
|
|
|
353
353
|
## Build Commands
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rust-kgdb",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.74",
|
|
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",
|