rust-kgdb 0.6.0 → 0.6.2

package/README.md

@@ -8,6 +8,27 @@
 
 ---
 
+## The Problem
+
+We asked GPT-4 to write a simple SPARQL query: *"Find all professors."*
+
+It returned this broken output:
+
+```text
+    ```sparql
+    SELECT ?professor WHERE { ?professor a ub:Faculty . }
+    ```
+    This query retrieves faculty members from the knowledge graph.
+```
+
+Three problems: (1) markdown code fences break the parser, (2) `ub:Faculty` doesn't exist in the schema (it's `ub:Professor`), and (3) the explanation text is mixed with the query. **Result: Parser error. Zero results.**
+
+This isn't a cherry-picked failure. When we ran the standard LUBM benchmark (14 queries, 3,272 triples), vanilla LLMs produced valid, correct SPARQL **0% of the time**.
+
+We built rust-kgdb to fix this.
+
+---
+
 ## Architecture: What Powers rust-kgdb
 
 ```
@@ -49,7 +70,9 @@
 
 **Key Insight**: The Rust core provides raw performance (2.78µs lookups). The HyperMind framework adds mathematical guarantees (type safety, composition laws, proof generation) without sacrificing speed.
 
-### What's Rust vs JavaScript?
+### What's Rust Core vs SDK Layer?
+
+All major capabilities are implemented in **Rust** via the HyperMind SDK crates (`hypermind-types`, `hypermind-runtime`, `hypermind-sdk`). The JavaScript/TypeScript layer is a thin binding that exposes these Rust capabilities for Node.js applications.
 
 | Component | Implementation | Performance | Notes |
 |-----------|---------------|-------------|-------|
@@ -58,37 +81,16 @@
 | **EmbeddingService** | Rust via NAPI-RS | Sub-ms search | HNSW index + 1-hop cache |
 | **DatalogProgram** | Rust via NAPI-RS | Semi-naive eval | Rule-based reasoning |
 | **Pregel** | Rust via NAPI-RS | BSP model | Iterative graph algorithms |
-| **TypeId** | JavaScript | N/A | Type system labels |
-| **LLMPlanner** | JavaScript + HTTP | LLM latency | Claude/GPT integration |
-| **WasmSandbox** | JavaScript Proxy | Capability check | All Rust calls proxied |
-| **AgentBuilder** | JavaScript | N/A | Fluent composition |
-| **ExecutionWitness** | JavaScript | SHA-256 | Cryptographic audit |
+| **TypeId** | Rust via NAPI-RS | N/A | Hindley-Milner type system |
+| **LLMPlanner** | JavaScript + HTTP | LLM latency | Orchestrates Rust tools via Claude/GPT |
+| **WasmSandbox** | Rust via NAPI-RS | Capability check | WASM isolation runtime |
+| **AgentBuilder** | Rust via NAPI-RS | N/A | Fluent tool composition |
+| **ExecutionWitness** | Rust via NAPI-RS | SHA-256 | Cryptographic audit proofs |
 
 **Security Model**: All interactions with Rust components flow through NAPI-RS bindings with memory isolation. The WasmSandbox wraps these bindings with capability-based access control, ensuring agents can only invoke tools they're explicitly granted. This provides defense-in-depth: NAPI-RS for memory safety, WasmSandbox for capability control.
 
 ---
 
-## The Problem
-
-We asked GPT-4 to write a simple SPARQL query: *"Find all professors."*
-
-It returned this:
-
-```sparql
-```sparql
-SELECT ?professor WHERE { ?professor a ub:Faculty . }
-```
-This query retrieves faculty members from the knowledge graph.
-```
-
-Three problems: markdown code fences break the parser, `ub:Faculty` doesn't exist in the schema (it's `ub:Professor`), and the explanation text is mixed with the query. **Result: Parser error. Zero results.**
-
-This isn't a cherry-picked failure. When we ran the standard LUBM benchmark (14 queries, 3,272 triples), vanilla LLMs produced valid, correct SPARQL **0% of the time**.
-
-We built rust-kgdb to fix this.
-
----
-
 ## The Solution
 
 rust-kgdb is a knowledge graph database with a neuro-symbolic agent framework called **HyperMind**. Instead of hoping the LLM gets the syntax right, we use mathematical type theory to *guarantee* correctness.
@@ -259,23 +261,32 @@ Token limits are real. rust-kgdb uses a **rolling time window strategy** to find
 └─────────────────────────────────────────────────────────────────────────────────┘
 ```
 
-### Idempotent Responses via Query Cache
+### Idempotent Responses via Semantic Hashing
 
-Same question = Same answer. Critical for compliance.
+Same question = Same answer. Even with **different wording**. Critical for compliance.
 
 ```javascript
-// First call: Compute answer, cache result
+// First call: Compute answer, cache with semantic hash
 const result1 = await agent.call("Analyze claims from Provider P001")
-// SHA-256 hash: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
+// Semantic Hash: semhash:fraud-provider-p001-claims-analysis
 
-// Second call (10 minutes later): Return cached result
-const result2 = await agent.call("Analyze claims from Provider P001")
-// Same hash: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
+// Second call (different wording, same intent): Cache HIT!
+const result2 = await agent.call("Show me P001's claim patterns")
+// Cache HIT - same semantic hash: semhash:fraud-provider-p001-claims-analysis
+
+// Third call (exact same): Also cache hit
+const result3 = await agent.call("Analyze claims from Provider P001")
+// Cache HIT - same semantic hash: semhash:fraud-provider-p001-claims-analysis
 
 // Compliance officer: "Why are these identical?"
-// You: "Idempotent responses - same input, same output, cryptographic proof."
+// You: "Semantic hashing - same meaning, same output, regardless of phrasing."
 ```
 
+**How it works**: Query embeddings are hashed via locality-sensitive hashing (LSH). Semantically similar queries map to the same bucket, enabling:
+- **Semantic deduplication** - "Find fraud" and "Detect fraudulent activity" hit same cache
+- **Cost reduction** - Avoid redundant LLM calls for paraphrased questions
+- **Consistency** - Same answer for same intent, audit-ready
+
 ---
 
 ## What This Is
@@ -2499,7 +2510,7 @@ that appear to be related. There might be collusion with provider PROV001."
     "output": "collusion(P001,P002,PROV001)",
     "derivation": "claim(CLM001,P001,PROV001) ∧ claim(CLM002,P002,PROV001) ∧ related(P001,P002) → collusion(P001,P002,PROV001)",
     "timestamp": "2024-12-14T10:30:00Z",
-    "hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
+    "semanticHash": "semhash:collusion-p001-p002-prov001"
   }
 }
 ```
@@ -2519,7 +2530,7 @@ that appear to be related. There might be collusion with provider PROV001."
 5. Unification: `?P1=P001, ?P2=P002, ?Prov=PROV001`
 6. Conclusion: `collusion(P001, P002, PROV001)` - QED
 
-Here's the SHA-256 hash of this execution: `9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08`"
+Here's the semantic hash: `semhash:collusion-p001-p002-prov001` - same query intent will always return this exact result."
 
 **Result:** HyperMind passes audit. DSPy gets you a follow-up meeting with legal.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Production-grade Neuro-Symbolic AI Framework with Memory Hypergraph: +86.4% accuracy improvement over vanilla LLMs. High-performance knowledge graph (2.78µs lookups, 35x faster than RDFox). Features Memory Hypergraph (temporal scoring, rolling context window, idempotent responses), fraud detection, underwriting agents, WASM sandbox, type/category/proof theory, and W3C SPARQL 1.1 compliance.",
   "main": "index.js",
   "types": "index.d.ts",