rust-kgdb 0.6.59 → 0.6.61

package/README.md

@@ -6,15 +6,15 @@
 
 ---
 
-## Why I Built This
+## The Problem With AI Today
 
-I spent years watching enterprise AI projects fail. Not because the technology was bad, but because we were using it wrong.
+Enterprise AI projects keep failing. Not because the technology is bad, but because organizations use it wrong.
 
 A claims investigator asks ChatGPT: *"Has Provider #4521 shown suspicious billing patterns?"*
 
 The AI responds confidently: *"Yes, Provider #4521 has a history of duplicate billing and upcoding."*
 
-The investigator opens a case. Weeks later, legal discovers **Provider #4521 has a perfect record**. The AI made it up. Now we're facing a lawsuit.
+The investigator opens a case. Weeks later, legal discovers **Provider #4521 has a perfect record**. The AI made it up. Lawsuit incoming.
 
 This keeps happening:
 
@@ -30,8 +30,6 @@ Every time, the same pattern: The AI sounds confident. The AI is wrong. People g
 
 ## The Engineering Problem
 
-I'm an engineer. I don't accept "that's just how LLMs work." I wanted to understand *why* this happens and *how* to fix it properly.
-
 **The root cause is simple:** LLMs are language models, not databases. They predict plausible text. They don't look up facts.
 
 When you ask "Has Provider #4521 shown suspicious patterns?", the LLM doesn't query your claims database. It generates text that *sounds like* an answer based on patterns from its training data.
@@ -40,20 +38,20 @@ When you ask "Has Provider #4521 shown suspicious patterns?", the LLM doesn't qu
 
 These help, but they're patches. RAG retrieves *similar* documents - similar isn't the same as *correct*. Fine-tuning teaches patterns, not facts. Guardrails catch obvious errors, but "Provider #4521 has billing anomalies" sounds perfectly plausible.
 
-**I wanted a real solution.** One built on solid engineering principles, not hope.
+**A real solution requires a different architecture.** One built on solid engineering principles, not hope.
 
 ---
 
-## The Insight
+## The Solution
 
-What if we stopped asking AI for **answers** and started asking it for **questions**?
+What if AI stopped providing **answers** and started generating **queries**?
 
 Think about it:
 - **Your database** knows the facts (claims, providers, transactions)
 - **AI** understands language (can parse "find suspicious patterns")
 - **You need both** working together
 
-The AI should translate intent into queries. The database should find facts. The AI should never make up data.
+The AI translates intent into queries. The database finds facts. The AI never makes up data.
 
 ```
 Before (Dangerous):
@@ -67,7 +65,7 @@ After (Safe):
   Result: Real data with audit trail ← VERIFIABLE
 ```
 
-This is what I built. A knowledge graph database with an AI layer that **cannot hallucinate** because it only returns data from your actual systems.
+rust-kgdb is a knowledge graph database with an AI layer that **cannot hallucinate** because it only returns data from your actual systems.
 
 ---
 
@@ -99,7 +97,7 @@ This is what I built. A knowledge graph database with an AI layer that **cannot
 
 **Two components, one npm package:**
 
-### 1. rust-kgdb Core: Embedded Knowledge Graph Database
+### rust-kgdb Core: Embedded Knowledge Graph Database
 
 A high-performance RDF/SPARQL database that runs **inside your application**. No server. No Docker. No config.
 
@@ -129,7 +127,7 @@ A high-performance RDF/SPARQL database that runs **inside your application**. No
 
 **Like SQLite - but for knowledge graphs.**
 
-### 2. HyperMind: Neuro-Symbolic Agent Framework
+### HyperMind: Neuro-Symbolic Agent Framework
 
 An AI agent layer that uses **the database to prevent hallucinations**. The LLM plans, the database executes.
 
@@ -211,6 +209,108 @@ These aren't arbitrary choices. Each one solves a real problem I encountered bui
 
 ---
 
+## Why Our Tool Calling Is Different
+
+Traditional AI tool calling (OpenAI Functions, LangChain Tools) has fundamental problems:
+
+**The Traditional Approach:**
+```
+LLM generates JSON → Runtime validates schema → Tool executes → Hope it works
+```
+
+1. **Schema is decorative.** The LLM sees a JSON schema and tries to match it. No guarantee outputs are correct types.
+2. **Composition is ad-hoc.** Chain Tool A → Tool B? Pray that A's output format happens to match B's input.
+3. **Errors happen at runtime.** You find out a tool chain is broken when a user hits it in production.
+4. **No mathematical guarantees.** "It usually works" is the best you get.
+
+**Our Approach: Tools as Typed Morphisms**
+```
+Tools are arrows in a category:
+  kg.sparql.query:     Query → BindingSet
+  kg.motif.find:       Pattern → Matches
+  kg.embeddings.search: EntityId → SimilarEntities
+
+Composition is verified:
+  f: A → B
+  g: B → C
+  g ∘ f: A → C  ✓ Compiles only if types match
+
+Errors caught at plan time, not runtime.
+```
+
+**What this means in practice:**
+
+| Problem | Traditional | HyperMind |
+|---------|-------------|-----------|
+| **Type mismatch** | Runtime error | Won't compile |
+| **Tool chaining** | Hope it works | Type-checked composition |
+| **Output validation** | Schema validation (partial) | Refinement types (complete) |
+| **Audit trail** | Optional logging | Built-in proof witnesses |
+
+**Refinement Types: Beyond Basic Types**
+
+We don't just have `string` and `number`. We have:
+- `RiskScore` (number between 0 and 1)
+- `PolicyNumber` (matches regex `^POL-\d{8}$`)
+- `CreditScore` (integer between 300 and 850)
+
+The type system *guarantees* a tool that outputs `RiskScore` produces a valid risk score. Not "probably" - mathematically proven.
+
+**The Insight:** Category theory isn't academic overhead. It's the same math that makes your database transactions safe (ACID = category theory applied to data). We apply it to tool composition.
+
+**Trust Model: Proxied Execution**
+
+Traditional tool calling trusts the LLM output completely:
+```
+LLM → Tool (direct execution) → Result
+```
+
+The LLM decides what to execute. The tool runs it blindly. This is why prompt injection attacks work - the LLM's output *is* the program.
+
+**Our approach: Agent → Proxy → Sandbox → Tool**
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Agent Request: "Find suspicious claims"                             │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  LLMPlanner: Generates tool call plan                                │
+│  → kg.sparql.query(pattern)                                          │
+│  → kg.datalog.infer(rules)                                           │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │ Plan (NOT executed yet)
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  HyperAgentProxy: Validates plan against capabilities                │
+│  ✓ Does agent have ReadKG capability? Yes                            │
+│  ✓ Is query schema-valid? Yes                                        │
+│  ✓ Are all types correct? Yes                                        │
+│  ✗ Blocked: WriteKG not in capability set                            │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │ Validated plan only
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  WasmSandbox: Executes with resource limits                          │
+│  • Fuel metering: 1M operations max                                  │
+│  • Memory cap: 64MB                                                  │
+│  • Capability enforcement: Cannot exceed granted permissions         │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │ Execution with audit
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  ProofDAG: Records execution witness                                 │
+│  • What tool ran                                                     │
+│  • What inputs were used                                             │
+│  • What outputs were produced                                        │
+│  • SHA-256 hash of entire execution                                  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+The LLM never executes directly. It proposes. The proxy validates. The sandbox enforces. The proof records. Four independent layers of defense.
+
+---
+
 ## What You Can Do
 
 | Query Type | Use Case | Example |

package/package.json

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