rust-kgdb 0.6.18 → 0.6.19

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
 
+## [0.6.19] - 2025-12-16
+
+### Documentation: The Power of the Concept
+
+Clear explanation of why HyperMind eliminates hallucinations.
+
+#### README.md - Before/After Comparison
+- **Side-by-side code**: Vanilla LLM (unreliable) vs HyperMind (verifiable)
+- **Visual problem markers**: ❌ for vanilla problems, ✅ for HyperMind solutions
+- **Concrete output examples**: Shows exactly what each approach returns
+
+#### README.md - Architecture Deep Dive
+- **4-step diagram**: Schema Injection → Typed Plan → Database Execution → Verified Answer
+- **"Why Hallucination Is Impossible" table**: Each step explained
+- **Key insight**: "The LLM is a planner, not an oracle"
+
+#### The Core Message
+```
+The LLM decides WHAT to look for.
+The database finds EXACTLY that.
+The answer is the intersection of LLM intelligence and database truth.
+```
+
+---
+
 ## [0.6.18] - 2025-12-16
 
 ### Documentation: Progressive Disclosure Structure

package/README.md

@@ -27,6 +27,62 @@
 
 ---
 
+## The Difference: Before & After
+
+### Before: Vanilla LLM (Unreliable)
+
+```javascript
+// Ask LLM to query your database
+const answer = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Find suspicious providers in my database' }]
+});
+
+console.log(answer.choices[0].message.content);
+// "Based on my analysis, Provider P001 appears suspicious because..."
+//
+// PROBLEMS:
+// ❌ Did it actually query your database? No - it's guessing
+// ❌ Where's the evidence? None - it made up "Provider P001"
+// ❌ Will this answer be the same tomorrow? No - probabilistic
+// ❌ Can you audit this for regulators? No - black box
+```
+
+### After: HyperMind (Verifiable)
+
+```javascript
+// Ask HyperMind to query your database
+const { HyperMindAgent, GraphDB } = require('rust-kgdb');
+
+const db = new GraphDB('http://insurance.org/');
+db.loadTtl(yourActualData, null);  // Your real data
+
+const agent = new HyperMindAgent({ kg: db, model: 'gpt-4o' });
+const result = await agent.call('Find suspicious providers');
+
+console.log(result.answer);
+// "Provider PROV001 has risk score 0.87 with 47 claims over $50,000"
+//
+// VERIFIED:
+// ✅ Queried your actual database (SPARQL executed)
+// ✅ Evidence included (47 real claims found)
+// ✅ Reproducible (same hash every time)
+// ✅ Full audit trail for regulators
+
+console.log(result.reasoningTrace);
+// [
+//   { tool: 'kg.sparql.query', input: 'SELECT ?p WHERE...', output: '[PROV001]' },
+//   { tool: 'kg.datalog.apply', input: 'highRisk(?p) :- ...', output: 'MATCHED' }
+// ]
+
+console.log(result.hash);
+// "sha256:8f3a2b1c..." - Same question = Same answer = Same hash
+```
+
+**The key insight**: The LLM plans WHAT to look for. The database finds EXACTLY that. Every answer traces back to your actual data.
+
+---
+
 ## Quick Start
 
 ### Installation
@@ -154,21 +210,70 @@ const result = await agent.call('Calculate risk score for entity P001')
 
 ## How It Works
 
-HyperMind combines two approaches:
-
-1. **Neural** (LLM): Understands your question in natural language
-2. **Symbolic** (Database): Executes precise queries against your data
+### The Architecture
 
 ```
-Your Question → LLM Plans Query → Database Executes → Verified Answer
-     ↓                ↓                  ↓                 ↓
-"Find fraud"   SELECT ?x WHERE...   47 results      "Provider P001
-                                                     is suspicious"
-                                                     + reasoning trace
-                                                     + audit hash
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              YOUR QUESTION                                   │
+│                    "Find suspicious providers"                               │
+└─────────────────────────────────┬───────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  STEP 1: SCHEMA INJECTION                                                    │
+│                                                                              │
+│  LLM receives your question PLUS your actual data schema:                   │
+│  • Classes: Claim, Provider, Policy (from YOUR database)                    │
+│  • Properties: amount, riskScore, claimCount (from YOUR database)           │
+│                                                                              │
+│  The LLM can ONLY reference things that actually exist in your data.        │
+└─────────────────────────────────┬───────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  STEP 2: TYPED EXECUTION PLAN                                                │
+│                                                                              │
+│  LLM generates a plan using typed tools:                                    │
+│  1. kg.sparql.query("SELECT ?p WHERE { ?p :riskScore ?r . FILTER(?r > 0.8)}")│
+│  2. kg.datalog.apply("suspicious(?p) :- highRisk(?p), highClaimCount(?p)")  │
+│                                                                              │
+│  Each tool has defined inputs/outputs. Invalid combinations rejected.        │
+└─────────────────────────────────┬───────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  STEP 3: DATABASE EXECUTION                                                  │
+│                                                                              │
+│  The database executes the plan against YOUR ACTUAL DATA:                   │
+│  • SPARQL query runs → finds 3 providers with riskScore > 0.8               │
+│  • Datalog rules run → 1 provider matches "suspicious" pattern              │
+│                                                                              │
+│  Every step is recorded in the reasoning trace.                             │
+└─────────────────────────────────┬───────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  STEP 4: VERIFIED ANSWER                                                     │
+│                                                                              │
+│  Answer: "Provider PROV001 is suspicious (riskScore: 0.87, claims: 47)"     │
+│                                                                              │
+│  + Reasoning Trace: Every query, every rule, every result                   │
+│  + Hash: sha256:8f3a2b1c... (reproducible)                                  │
+│                                                                              │
+│  Run the same question tomorrow → Same answer → Same hash                   │
+└─────────────────────────────────────────────────────────────────────────────┘
 ```
 
-The LLM plans WHAT to look for. The database finds EXACTLY that. Every answer traces back to actual data. No hallucination possible.
+### Why Hallucination Is Impossible
+
+| Step | What Prevents Hallucination |
+|------|----------------------------|
+| Schema Injection | LLM only sees properties that exist in YOUR data |
+| Typed Tools | Invalid query structures rejected before execution |
+| Database Execution | Answers come from actual data, not LLM imagination |
+| Reasoning Trace | Every claim is backed by recorded evidence |
+
+**The key insight**: The LLM is a planner, not an oracle. It decides WHAT to look for. The database finds EXACTLY that. The answer is the intersection of LLM intelligence and database truth.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "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.",
   "main": "index.js",
   "types": "index.d.ts",