rust-kgdb 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
 
+## [0.8.1] - 2025-12-21
+
+### Documentation & README Updates
+
+- Added comprehensive ThinkingReasoner documentation section to README
+- Updated "What's New" section with v0.8.0 features at top
+- Added ThinkingReasoner to Engineering Foundation table
+- Expanded derivation chain examples with insurance fraud detection scenario
+- Added "The Setup Data" section explaining synthetic ontologies
+
+---
+
 ## [0.8.0] - 2025-12-21
 
 ### ThinkingReasoner: When AI Shows Its Work

package/README.md

@@ -7,6 +7,65 @@
 > **Your knowledge is scattered. Your claims live in Snowflake. Your customer graph sits in Neo4j. Your risk models run on BigQuery. Your compliance docs are in SharePoint. And your AI? It hallucinates because it can't see the full picture.**
 >
 > rust-kgdb unifies scattered enterprise knowledge into a single queryable graph—with native embeddings, cross-database federation, and AI that generates queries instead of fabricating answers. No hallucinations. Full audit trails. One query across everything.
+>
+> **What makes it different?** Totally in-memory KGDB with memory acceleration (449ns lookups). Multi-way federated joins across KGDB + Snowflake + BigQuery in a single SQL statement. W3C DCAT/DPROD data cataloging for self-describing data products. And now: **ThinkingReasoner**—deductive AI with proof-carrying outputs where every conclusion has a cryptographic derivation chain.
+
+---
+
+## What's New in v0.8.0
+
+**What if every AI conclusion came with a mathematical proof?**
+
+| Feature | Description | Performance |
+|---------|-------------|-------------|
+| **ThinkingReasoner** | Generic ontology-driven deductive reasoning engine | 6 rules auto-generated from ontology |
+| **Thinking Events** | Append-only event sourcing for AI reasoning steps | Observations, hypotheses, inferences |
+| **Proof-Carrying Outputs** | Cryptographic proofs via Curry-Howard correspondence | SHA-256 hash per derivation |
+| **Derivation Chain** | Step-by-step reasoning visualization | 7-step trace with premises |
+| **Auto-Generated Rules** | Rules from OWL/RDFS properties, not hardcoded | Transitive, symmetric, subclass |
+
+```javascript
+const { ThinkingReasoner } = require('rust-kgdb')
+
+// Load YOUR ontology - rules are auto-generated, not hardcoded
+const reasoner = new ThinkingReasoner()
+reasoner.loadOntology(`
+  @prefix ins: <http://insurance.example.org/> .
+  @prefix owl: <http://www.w3.org/2002/07/owl#> .
+
+  # This single line auto-generates transitivity rules
+  ins:transfers a owl:TransitiveProperty .
+`)
+
+// Record observations (ground truth from your data)
+reasoner.observe("Alice transfers $10K to Bob", { subject: "alice", predicate: "transfers", object: "bob" })
+reasoner.observe("Bob transfers $9.5K to Carol", { subject: "bob", predicate: "transfers", object: "carol" })
+reasoner.observe("Carol transfers $9K to Alice", { subject: "carol", predicate: "transfers", object: "alice" })
+
+// Run deduction - derives: alice transfers to carol (transitivity!)
+const result = reasoner.deduce()
+// result.derivedFacts: 3 new facts
+// result.proofs: 3 cryptographic witnesses
+// result.derivationChain: step-by-step reasoning trace
+```
+
+**The key insight**: The LLM proposes hypotheses. The ThinkingReasoner validates them against your ontology. Only facts with valid proofs become assertions. No hallucinations possible—every conclusion traces back through a derivation chain to ground truth observations.
+
+```
+Derivation Chain (like Claude's thinking, but verifiable):
+
+  Step 1: [OBSERVATION] Alice transfers to Bob
+  Step 2: [OBSERVATION] Bob transfers to Carol
+  Step 3: [RULE: owl:TransitiveProperty] Alice transfers to Carol
+          Premises: [Step 1, Step 2]
+          Proof Hash: a3f8c2...
+  Step 4: [OBSERVATION] Carol transfers to Alice
+  Step 5: [RULE: circularPayment] Circular payment detected: Alice → Bob → Carol → Alice
+          Premises: [Step 1, Step 2, Step 4]
+          Confidence: 0.85
+```
+
+*See [ThinkingReasoner: Deductive AI](#thinkingreasoner-deductive-ai) for complete documentation.*
 
 ---
 
@@ -207,6 +266,7 @@ At no point does the AI "know" anything. It's a translator—from human intent t
 | **Analytics** | GraphFrames | PageRank, connected components, triangle count, motif matching |
 | **Analytics** | Pregel API | Bulk synchronous parallel graph algorithms |
 | **Reasoning** | Datalog Engine | Recursive rule evaluation with fixpoint semantics |
+| **Reasoning** | ThinkingReasoner | Ontology-driven deduction with proof-carrying outputs |
 | **AI Agent** | HyperMindAgent | Schema-aware SPARQL generation from natural language |
 | **AI Agent** | Type System | Hindley-Milner type inference for query validation |
 | **AI Agent** | Proof DAG | SHA-256 audit trail for every AI decision |
@@ -1660,6 +1720,246 @@ const agent = new AgentBuilder('scoped-agent')
 
 ---
 
+## ThinkingReasoner: Deductive AI
+
+### The Problem: AI That Can't Show Its Work
+
+When a fraud analyst asks your AI: *"Is this circular payment pattern suspicious?"*
+
+What happens today:
+- **GPT-4**: "Yes, this appears to be money laundering." (Confidence: high. Evidence: none.)
+- **Claude**: "The pattern suggests fraudulent activity." (Sounds authoritative. No proof.)
+- **LLaMA**: "Based on typical patterns..." (Based on what exactly?)
+
+Every AI system gives confident answers. None can explain *how* they reached them. None can prove they're correct. None can trace the reasoning chain back to your actual data.
+
+This is the hallucination problem at its core: **AI generates conclusions without derivations.**
+
+### The Solution: Proof-Carrying Outputs
+
+What if every AI conclusion came with a cryptographic proof?
+
+```
+Traditional AI:
+  Input: "Is Alice → Bob → Carol → Alice suspicious?"
+  Output: "Yes, this is suspicious."  ← UNVERIFIED CLAIM
+
+ThinkingReasoner:
+  Input: "Is Alice → Bob → Carol → Alice suspicious?"
+  Output:
+    Conclusion: "Circular payment pattern detected"
+    Proof Hash: a3f8c2e7...
+    Derivation Chain:
+      [1] OBSERVATION: Alice transfers to Bob (fact from database)
+      [2] OBSERVATION: Bob transfers to Carol (fact from database)
+      [3] OBSERVATION: Carol transfers to Alice (fact from database)
+      [4] RULE: owl:TransitiveProperty → Alice transfers to Carol
+      [5] RULE: circularPayment(A,B,C) :- A→B, B→C, C→A
+      [6] CONCLUSION: circularPayment(Alice, Bob, Carol) ← VERIFIABLE
+```
+
+**The difference**: Every conclusion has a derivation chain. Every derivation step cites its source (observation or rule). Every chain can be replayed to verify correctness. No hallucinations possible.
+
+### The Mathematical Foundation
+
+The ThinkingReasoner implements three interconnected theories:
+
+**1. Event Sourcing (Ground Truth)**
+```javascript
+// Every observation is append-only, immutable, timestamped
+reasoner.observe("Alice transfers $10K to Bob", {
+  subject: "http://example.org/alice",
+  predicate: "http://example.org/transfers",
+  object: "http://example.org/bob",
+  timestamp: "2025-12-21T10:30:00Z",
+  source: "banking-system-export"
+})
+```
+Observations are facts from your systems. They can't be modified. They form the ground truth for all reasoning.
+
+**2. Ontology-Driven Rules (No Hardcoding)**
+```javascript
+// Load YOUR ontology - rules are auto-generated
+reasoner.loadOntology(`
+  @prefix owl: <http://www.w3.org/2002/07/owl#> .
+  @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+  # This single line generates: transfers(A,C) :- transfers(A,B), transfers(B,C)
+  :transfers a owl:TransitiveProperty .
+
+  # This generates: relatedTo(B,A) :- relatedTo(A,B)
+  :relatedTo a owl:SymmetricProperty .
+
+  # This generates: Claim(X) :- FraudulentClaim(X)
+  :FraudulentClaim rdfs:subClassOf :Claim .
+`)
+```
+Rules aren't hardcoded in your application. They're derived from OWL/RDFS properties in your ontology. Change the ontology, change the rules. No code changes required.
+
+**3. Curry-Howard Correspondence (Proofs as Programs)**
+```
+Every assertion A has a proof P such that:
+  - P.conclusion = A
+  - P.premises ⊆ (Observations ∪ DerivedFacts)
+  - P.rules ⊆ OntologyRules
+  - P.hash = SHA-256(P.conclusion, P.premises, P.rules)
+```
+This is the Curry-Howard correspondence: proofs are programs, propositions are types. An assertion without a proof is a type without an inhabitant—it doesn't exist.
+
+### Complete API Example
+
+```javascript
+const { ThinkingReasoner } = require('rust-kgdb')
+
+// Create reasoner for fraud detection domain
+const reasoner = new ThinkingReasoner()
+
+// Load insurance/fraud ontology
+reasoner.loadOntology(`
+  @prefix ins: <http://insurance.example.org/> .
+  @prefix owl: <http://www.w3.org/2002/07/owl#> .
+  @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+  # Transitivity: if A transfers to B, and B transfers to C, then A transfers to C
+  ins:transfers a owl:TransitiveProperty .
+
+  # Symmetry: if A is related to B, then B is related to A
+  ins:relatedTo a owl:SymmetricProperty .
+
+  # Hierarchy: FraudulentClaim is a subclass of Claim
+  ins:FraudulentClaim rdfs:subClassOf ins:Claim .
+  ins:HighRiskClaim rdfs:subClassOf ins:Claim .
+`)
+
+// Record observations from your data sources
+const obs1 = reasoner.observe("Alice transfers $10K to Bob", {
+  subject: "ins:alice",
+  predicate: "ins:transfers",
+  object: "ins:bob"
+})
+
+const obs2 = reasoner.observe("Bob transfers $9.5K to Carol", {
+  subject: "ins:bob",
+  predicate: "ins:transfers",
+  object: "ins:carol"
+})
+
+const obs3 = reasoner.observe("Carol transfers $9K to Alice", {
+  subject: "ins:carol",
+  predicate: "ins:transfers",
+  object: "ins:alice"
+})
+
+// Record a hypothesis (LLM-proposed, needs verification)
+const hyp = reasoner.hypothesize(
+  "Circular payment fraud detected",
+  {
+    subject: "ins:alice",
+    predicate: "ins:suspectedFraud",
+    object: "circular-payment-pattern",
+    confidence: 0.85
+  },
+  [obs1, obs2, obs3]  // Supporting observations
+)
+
+// Run deduction - validates hypothesis against ontology rules
+const result = reasoner.deduce()
+
+console.log(`Rules fired: ${result.rulesFired}`)           // 6
+console.log(`Derived facts: ${result.derivedFacts.length}`)  // 3
+console.log(`Proofs generated: ${result.proofs.length}`)     // 3
+
+// Get the thinking graph (for visualization)
+const graph = reasoner.getThinkingGraph()
+
+console.log(`Nodes: ${graph.nodes.length}`)      // Events + Facts
+console.log(`Edges: ${graph.edges.length}`)      // Causal relationships
+console.log(`Derivation steps: ${graph.derivationChain.length}`)  // 7
+
+// Display derivation chain (like Claude's thinking, but verifiable)
+for (const step of graph.derivationChain) {
+  console.log(`Step ${step.step}: [${step.rule}] ${step.conclusion}`)
+  if (step.premises.length > 0) {
+    console.log(`  Premises: ${step.premises.join(', ')}`)
+  }
+}
+```
+
+### Output: Derivation Chain
+
+```
+[1] Creating ThinkingContext...
+    Context ID: fraud-detection-session
+    Actor ID: fraud-agent-001
+
+[2] Loading insurance ontology...
+    Auto-generated 6 rules from ontology
+    - Transitivity rules for ins:transfers
+    - Symmetry rules for ins:relatedTo
+    - SubClass inference rules
+
+[3] Recording observations...
+    Observation 1: Alice → Bob (ID: obs_001)
+    Observation 2: Bob → Carol (ID: obs_002)
+    Observation 3: Carol → Alice (ID: obs_003)
+
+[4] Recording hypothesis...
+    Hypothesis recorded (ID: hyp_001)
+    Confidence: 0.85
+    Based on observations: [obs_001, obs_002, obs_003]
+
+[5] Running deduction...
+    Deduction complete!
+    - Rules fired: 6
+    - Iterations: 3
+    - Derived facts: 3
+    - Proofs generated: 3
+
+[6] Derivation Chain:
+    Step 1: [OBSERVATION] ins:alice ins:transfers ins:bob
+    Step 2: [OBSERVATION] ins:bob ins:transfers ins:carol
+    Step 3: [owl:TransitiveProperty] ins:alice ins:transfers ins:carol
+            Premises: [Step 1, Step 2]
+    Step 4: [OBSERVATION] ins:carol ins:transfers ins:alice
+    Step 5: [owl:TransitiveProperty] ins:bob ins:transfers ins:alice
+            Premises: [Step 2, Step 4]
+    Step 6: [owl:TransitiveProperty] ins:alice ins:transfers ins:alice
+            Premises: [Step 1, Step 5]
+    Step 7: [circularPayment] Circular payment detected
+            Premises: [Step 1, Step 2, Step 4]
+            Confidence: 0.85
+            Proof Hash: a3f8c2e7...
+```
+
+### Why This Matters
+
+| Capability | Traditional AI | ThinkingReasoner |
+|------------|----------------|------------------|
+| **Confidence scores** | Made up by LLM | Derived from proof chain |
+| **Explanation** | "Based on patterns..." | Step-by-step derivation |
+| **Verification** | Trust the AI | Replay the proof |
+| **Audit trail** | None | SHA-256 cryptographic hash |
+| **Rule changes** | Retrain model | Update ontology |
+| **Domain adaptation** | Fine-tuning ($$$) | Load new ontology (free) |
+
+### The Setup Data
+
+The ThinkingReasoner demo uses synthetic inline ontologies:
+
+**Insurance Ontology** (fraud detection):
+- `ins:transfers` as `owl:TransitiveProperty` (payment chain detection)
+- `ins:relatedTo` as `owl:SymmetricProperty` (relationship inference)
+- `ins:FraudulentClaim rdfs:subClassOf ins:Claim` (type hierarchy)
+
+**Underwriting Ontology** (risk assessment):
+- `uw:HighRiskApplicant rdfs:subClassOf uw:Applicant`
+- `uw:employs` as `owl:TransitiveProperty` (employment verification)
+- `uw:hasRiskIndicator` with domain/range constraints
+
+No external datasets required. Load your own ontology for your domain.
+
+---
+
 ## HyperFederate: Cross-Database Federation
 
 ### The Real Problem: Your Knowledge Lives Everywhere

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "High-performance RDF/SPARQL database with AI agent framework and cross-database federation. GraphDB (449ns lookups, 5-11x faster than RDFox), HyperFederate (KGDB + Snowflake + BigQuery), GraphFrames analytics, 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",