rust-kgdb 0.6.59 → 0.6.60

package/README.md

@@ -99,7 +99,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 +129,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 +211,57 @@ 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.
+
+---
+
 ## 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.60",
   "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",