rust-kgdb 0.6.72 → 0.6.73

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 (5) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/DESIGN.md +34 -34
  3. package/IMPLEMENTATION_GUIDE.md +35 -35
  4. package/README.md +24 -0
  5. 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
- │ HYPERMIND ARCHITECTURE │
10
- ├─────────────────────────────────────────────────────────────────────────────┤
11
- │ │
12
- │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
13
- │ │ User │ │ Schema │ │ LLM │ │ Typed │ │
14
- │ │ Query │ -> │ Context │ -> │ Planner │ -> │ Tools │ │
15
- │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
16
- │ │ │ │
17
- │ │ ▼ │
18
- │ │ ┌─────────────┐ │
19
- │ │ │ Database │ │
20
- │ │ │ Execution │ │
21
- │ │ └─────────────┘ │
22
- │ │ │ │
23
- │ ▼ ▼ │
24
- │ ┌─────────────────────────────────────────────────┐ │
25
- │ │ Reasoning Trace │ │
26
- │ │ (Every step recorded with cryptographic hash) │ │
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" → "teacherOf"
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% → 85.7%)
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 → Course → Department)
142
+ - **Composition** = Property paths (Professor -> Course -> Department)
143
143
 
144
144
  ```
145
- Professor ──teacherOf──▶ Course ──offeredBy──▶ Department
146
- │ │
147
- └────────────worksFor──────────────────────────┘
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 → Result (proof = program)
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 → LLM → Text Output
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 → LLM → Structured Output
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 → LLM Planner → Typed Tools → Database → Verified Answer
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
- │ ARCHITECTURE OVERVIEW │
23
- │ │
24
- │ YOUR APPLICATION (Node.js / TypeScript) │
25
- │ │ │
26
- │ ▼ │
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
- │ ▼ ▼ │
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
- └─────────────────────────────────────────────────────────────────────────────┘
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 → {domain, range}
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
- ├── 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)
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/README.md CHANGED
@@ -8,6 +8,30 @@
8
8
 
9
9
  ---
10
10
 
11
+ ## Documentation Guide (Reading Order)
12
+
13
+ For engineers new to rust-kgdb, read in this order:
14
+
15
+ | Order | Document | Purpose | Time |
16
+ |-------|----------|---------|------|
17
+ | 1 | **README.md** (this file) | Why rust-kgdb exists, what problem it solves, architecture overview | 15 min |
18
+ | 2 | **[Quick Start](#quick-start)** | Get running with 5 lines of code | 5 min |
19
+ | 3 | **[DESIGN.md](./DESIGN.md)** | HyperMind architecture: Schema Context, Predicate Resolver, Typed Tools | 20 min |
20
+ | 4 | **[IMPLEMENTATION_GUIDE.md](./IMPLEMENTATION_GUIDE.md)** | Step-by-step implementation: SPARQL, Datalog, Motif, GraphFrames | 30 min |
21
+ | 5 | **[examples/](./examples/)** | Working code: fraud detection, underwriting, graph analytics | 30 min |
22
+ | 6 | **[HYPERMIND_BENCHMARK_REPORT.md](./HYPERMIND_BENCHMARK_REPORT.md)** | Detailed benchmark methodology and results | 15 min |
23
+ | 7 | **[CHANGELOG.md](./CHANGELOG.md)** | Version history and feature additions | 5 min |
24
+
25
+ **Quick Links:**
26
+ - [Installation](#installation) - `npm install rust-kgdb`
27
+ - [SPARQL Examples](#hypermind-where-neural-meets-symbolic)
28
+ - [Datalog Examples](#hypermind-where-neural-meets-symbolic)
29
+ - [GraphFrame Examples](#feature-overview)
30
+ - [Fraud Detection](#production-example-fraud-detection)
31
+ - [Benchmarks](#published-benchmarks)
32
+
33
+ ---
34
+
11
35
  ## The Problem With AI Today
12
36
 
13
37
  Enterprise AI projects keep failing. Not because the technology is bad, but because organizations use it wrong.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rust-kgdb",
3
- "version": "0.6.72",
3
+ "version": "0.6.73",
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",