rust-kgdb 0.8.17 → 0.8.19

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
 
+## [0.8.18] - 2025-12-24
+
+### Documentation: Examples Now in Dedicated Repository
+
+All examples now live in [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples) - a dedicated repository with video demos, working code, and 100% pass rates.
+
+#### Changes
+
+- **README**: All example commands now point to hypermind-examples repo (not node_modules)
+- **Package Size**: Reduced by removing bundled examples (users clone repo instead)
+- **Clarity**: Single source of truth for all working demos
+
+#### How to Run Examples
+
+```bash
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples && npm install
+npm run self-driving-car  # 3D explainable AI demo
+npm run brain             # BRAIN fraud + underwriting
+npm run euroleague        # Basketball analytics
+npm run boston            # Real estate analysis
+npm run legal             # Legal case reasoning
+```
+
+---
+
 ## [0.8.17] - 2025-12-24
 
 ### Explainable AI for Autonomous Vehicles + Complete Demo Suite

package/README.md

@@ -31,27 +31,46 @@ Traditional LLM:                         BRAIN HyperMind Agent:
 
 **Try it now:**
 ```bash
-npm install rust-kgdb
-node node_modules/rust-kgdb/examples/fraud-underwriting-reallife-demo.js
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples && npm install
+npm run brain  # BRAIN Fraud & Underwriting demo
 ```
 
 ---
 
-## What's New in v0.8.17
+## What's New in v0.8.19
+
+**All examples now in [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples) repository**
+
+### Real-World Demos That Actually Work
+
+Most AI demos are impressive until you look under the hood. Ours are different—every answer is grounded in a knowledge graph, every recommendation has a reason, every conclusion has a proof.
 
-**Explainable AI for Autonomous Vehicles + Full Demo Suite**
+| Demo | What It Proves | Why It Matters |
+|------|----------------|----------------|
+| **Digital Twin** | IoT + OWL reasoning for smart buildings | Decisions with SHA-256 proof trails |
+| **Music Recommendation** | Graph similarity, not vibes | "Slayer for Metallica" because thrash metal lineage, not random |
+| **Self-Driving Car** | Explainable perception decisions | Every brake/accelerate is SPARQL-derived |
+| **BRAIN Fraud Detection** | Cross-database federation | KGDB + Snowflake + BigQuery in one query |
+| **Euroleague Analytics** | Sports stats with deductive reasoning | 111 observations → 222 derived facts |
 
-| Feature | What It Does | The Proof |
-|---------|--------------|-----------|
-| **Self-Driving Car Demo** | 3D explainable AI for autonomous vehicles | SPARQL + Datalog + Hypergraph reasoning |
-| **BRAIN Framework** | Fraud detection + Underwriting with HyperFederate | KGDB + Snowflake + BigQuery in single query |
-| **ThinkingReasoner** | Deductive engine that SHOWS ITS WORK | 111 observations → 222 derived facts |
-| **RDF2Vec Embeddings** | Graph embeddings trained IN-MEMORY | 384D vectors, HNSW similarity |
-| **Cryptographic Proofs** | SHA-256 hash per derivation step | Curry-Howard correspondence |
+**The difference?** When we say "Megadeth is similar to Metallica," we can show you the graph path: same genre (thrash metal), shared influence (Black Sabbath), 1-hop distance. Not a probability. A derivation.
+
+### Try It Now
+
+```bash
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples && npm install
+
+npm run digital-twin  # IoT + Datalog rules
+npm run music         # Graph-based recommendations
+npm run brain         # Fraud + Underwriting
+npm run self-driving-car  # Explainable AV decisions
+```
 
 ### Complete Working Examples
 
-**All demos at 100% pass rate:** [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples)
+**All demos verified:** [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples)
 
 ```bash
 git clone https://github.com/gonnect-uk/hypermind-examples.git
@@ -90,22 +109,23 @@ That's **real SPARQL**, **real results**, **real proofs**. No mocking. No hardco
 
 ### Demo Validation Results (2025-12-24)
 
-All demos verified and running at **100% pass rate**. See [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples) for complete working examples.
+All demos verified from local execution. See [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples).
 
-| Demo | Assertions | Pass Rate | Command |
-|------|------------|-----------|---------|
-| **Self-Driving Car** | 3 scenarios | 100% | `npm run self-driving-car` |
-| **BRAIN Fraud & Underwriting** | 5 scenarios | 100% | `npm run brain` |
-| **Euroleague Analytics** | 18 tests | 100% | `npm run euroleague` |
-| **Boston Real Estate** | 19 tests | 100% | `npm run boston` |
-| **US Legal Case** | 20 tests | 100% | `npm run legal` |
+| Demo | Tests | Pass Rate | What You'll See |
+|------|-------|-----------|-----------------|
+| **Digital Twin** | 13 | 100% | IoT sensors → Datalog rules → HVAC decisions with proofs |
+| **Music Recommendation** | 14 | 93.3% | KG-grounded: "Slayer, Megadeth for Metallica" with graph paths |
+| **Self-Driving Car** | 3 | 100% | Explainable AV: "Brake because pedestrian in crosswalk" |
+| **BRAIN Fraud** | 5 | 100% | Cross-database: KGDB + Snowflake + BigQuery |
+| **Euroleague Analytics** | 18 | 100% | ThinkingReasoner: 111 obs → 222 derived facts |
+| **Boston Real Estate** | 19 | 100% | OWL SymmetricProperty: adjacentTo auto-inferred |
+| **US Legal Case** | 20 | 100% | Legal research with precedent chains |
 
-**Key Features Demonstrated:**
-- ThinkingReasoner with OWL property auto-detection
-- RDF2Vec embeddings (384D, trained in-memory)
-- HyperFederate (KGDB + Snowflake + BigQuery)
-- Cryptographic proofs (SHA-256 per derivation)
-- Episodic memory for pattern matching
+**What makes these different from typical demos:**
+- No mocking. Real SPARQL, real data, real results.
+- Every recommendation explains WHY (not just WHAT)
+- Proofs are SHA-256 hashes over canonical derivation chains
+- LLM is optional—core reasoning is deterministic
 
 ---
 
@@ -2729,9 +2749,12 @@ main().catch(console.error)
 
 ## HyperMind Architecture Deep Dive
 
-For a complete walkthrough of the architecture, run:
+For complete working examples, see [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples):
 ```bash
-node examples/hypermind-agent-architecture.js
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples && npm install
+npm run euroleague   # Euroleague analytics demo
+npm run brain        # BRAIN Fraud & Underwriting
 ```
 
 ### Full System Architecture
@@ -2980,7 +3003,7 @@ Result: ✅ 15 results returned in 2.3ms
 
 ## HyperMind in Action: Complete Agent Conversation
 
-This is what a real HyperMind agent interaction looks like. Run `node examples/hypermind-complete-demo.js` to see it yourself.
+This is what a real HyperMind agent interaction looks like. See [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples) for working demos.
 
 ```
 ================================================================================
@@ -3097,11 +3120,13 @@ This is what a real HyperMind agent interaction looks like. Run `node examples/h
 - **Vanilla LLM**: "Some claims may be suspicious" (no data access, no proof)
 - **HyperMind**: Specific findings + rule derivations + cryptographic audit trail
 
-**Try it yourself:**
+**Try it yourself:** [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples)
 ```bash
-node examples/hypermind-complete-demo.js  # Full 7-section demo
-node examples/fraud-detection-agent.js    # Fraud detection pipeline
-node examples/underwriting-agent.js       # Underwriting pipeline
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples && npm install
+npm run brain       # BRAIN Fraud & Underwriting pipeline
+npm run euroleague  # Euroleague analytics demo
+npm run legal       # US Legal Case reasoning
 ```
 
 ---
@@ -3403,9 +3428,10 @@ async function runFraudDetection() {
 runFraudDetection()
 ```
 
-**Run it yourself:**
+**Run it yourself:** [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples)
 ```bash
-node examples/fraud-detection-agent.js
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples && npm install && npm run brain
 ```
 
 **Actual Output:**
@@ -3496,9 +3522,10 @@ console.log('Auto-approve:', decisions.autoApprove)  // [["BUS002"]]
 console.log('Refer to UW:', decisions.referToUW)     // [["BUS003"]]
 ```
 
-**Run it yourself:**
+**Run it yourself:** [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples)
 ```bash
-node examples/underwriting-agent.js
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples && npm install && npm run brain
 ```
 
 **Actual Output:**
@@ -3985,18 +4012,17 @@ async function runFraudDetectionAgent() {
 
 ### Run the Complete Examples
 
-```bash
-# Fraud Detection Agent (full pipeline)
-node examples/fraud-detection-agent.js
+See [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples) for all working demos:
 
-# Underwriting Agent (full pipeline)
-node examples/underwriting-agent.js
+```bash
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples && npm install
 
-# With real LLM (Anthropic)
-ANTHROPIC_API_KEY=sk-ant-... node examples/fraud-detection-agent.js
+# BRAIN Fraud & Underwriting (full pipeline)
+npm run brain
 
-# With real LLM (OpenAI)
-OPENAI_API_KEY=sk-proj-... node examples/underwriting-agent.js
+# With real LLM (set API key)
+OPENAI_API_KEY=sk-proj-... npm run brain
 ```
 
 ### The Complete Picture

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.8.17",
+  "version": "0.8.19",
   "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",
@@ -77,17 +77,10 @@
     "index.js",
     "index.d.ts",
     "hypermind-agent.js",
-    "secure-agent-sandbox-demo.js",
-    "vanilla-vs-hypermind-benchmark.js",
-    "benchmark-frameworks.py",
-    "verified_benchmark_results.json",
-    "examples/",
     "ontology/",
     "README.md",
     "CLAUDE.md",
     "DESIGN.md",
-    "IMPLEMENTATION_GUIDE.md",
-    "HYPERMIND_BENCHMARK_REPORT.md",
     "CHANGELOG.md",
     "*.node"
   ]