rust-kgdb 0.6.18 → 0.6.20

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
@@ -126,49 +182,132 @@ const result = await agent.call('Calculate risk score for entity P001')
 
 ## Features
 
-### Core Database
-- **SPARQL 1.1** - Full query and update support (64 builtin functions)
-- **RDF 1.2** - Complete W3C standard implementation
-- **RDF-Star** - Statements about statements
-- **Hypergraph** - N-ary relationships beyond triples
-
-### Graph Analytics
-- **PageRank** - Iterative ranking algorithm
-- **Connected Components** - Community detection
-- **Shortest Paths** - Path finding
-- **Triangle Count** - Graph density
-- **Motif Finding** - Pattern matching
-
-### AI Agent Framework
-- **Schema-Aware** - Auto-extracts schema from your data
-- **Typed Tools** - Input/output validation prevents errors
-- **Audit Trail** - Every answer is traceable
-- **Memory** - Working, episodic, and long-term memory
+### Core Database (SPARQL 1.1)
+| Feature | Description |
+|---------|-------------|
+| **SELECT/CONSTRUCT/ASK** | Full SPARQL 1.1 query support |
+| **INSERT/DELETE/UPDATE** | SPARQL Update operations |
+| **64 Builtin Functions** | String, numeric, date/time, hash functions |
+| **Named Graphs** | Quad-based storage with graph isolation |
+| **RDF-Star** | Statements about statements |
+
+### Rule-Based Reasoning (Datalog)
+| Feature | Description |
+|---------|-------------|
+| **Facts & Rules** | Define base facts and inference rules |
+| **Semi-naive Evaluation** | Efficient incremental computation |
+| **Recursive Queries** | Transitive closure, ancestor chains |
+
+### Graph Analytics (GraphFrames)
+| Feature | Description |
+|---------|-------------|
+| **PageRank** | Iterative node importance ranking |
+| **Connected Components** | Find isolated subgraphs |
+| **Shortest Paths** | BFS path finding from landmarks |
+| **Triangle Count** | Graph density measurement |
+| **Motif Finding** | Structural pattern matching DSL |
+
+### Vector Similarity (Embeddings)
+| Feature | Description |
+|---------|-------------|
+| **HNSW Index** | O(log N) approximate nearest neighbor |
+| **Multi-provider** | OpenAI, Anthropic, Ollama support |
+| **Composite Search** | RRF aggregation across providers |
+
+### AI Agent Framework (HyperMind)
+| Feature | Description |
+|---------|-------------|
+| **Schema-Aware** | Auto-extracts schema from your data |
+| **Typed Tools** | Input/output validation prevents errors |
+| **Audit Trail** | Every answer is traceable |
+| **Memory** | Working, episodic, and long-term memory |
+
+### Available Tools
+| Tool | Input → Output | Description |
+|------|----------------|-------------|
+| `kg.sparql.query` | Query → BindingSet | Execute SPARQL SELECT |
+| `kg.sparql.update` | Update → Result | Execute SPARQL UPDATE |
+| `kg.datalog.apply` | Rules → InferredFacts | Apply Datalog rules |
+| `kg.motif.find` | Pattern → Matches | Find graph patterns |
+| `kg.embeddings.search` | Entity → SimilarEntities | Vector similarity |
+| `kg.graphframes.pagerank` | Graph → Scores | Rank nodes |
+| `kg.graphframes.components` | Graph → Components | Find communities |
 
 ### Performance
-- **2.78 µs** lookup speed (35x faster than RDFox)
-- **146K triples/sec** bulk insert
-- **24 bytes/triple** memory efficiency
+| Metric | Value | Comparison |
+|--------|-------|------------|
+| **Lookup Speed** | 2.78 µs | 35x faster than RDFox |
+| **Bulk Insert** | 146K triples/sec | Production-grade |
+| **Memory** | 24 bytes/triple | Best-in-class efficiency |
 
 ---
 
 ## 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.20",
   "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",