rust-kgdb 0.6.47 → 0.6.49

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
 
+## [0.6.49] - 2025-12-17
+
+### Core Concepts Section Added
+
+#### New "What We Bring and Why" Section
+Simple Problem → Solution format explaining our 5 core innovations:
+
+1. **Schema-Aware Query Generation**
+   - Problem: LLMs hallucinate predicates
+   - Solution: Auto-extract schema, inject into prompts
+
+2. **Built-in Database (Not BYODB)**
+   - Problem: Other frameworks generate queries but need external DB
+   - Solution: rust-kgdb IS the database
+
+3. **Audit Trail (Provenance)**
+   - Problem: Where did that answer come from?
+   - Solution: Full reasoning trace with every answer
+
+4. **Deterministic Execution**
+   - Problem: Same question → different answers
+   - Solution: Same hash for same input (compliance-ready)
+
+5. **ARCADE 1-Hop Cache**
+   - Problem: Slow embedding neighborhood lookups
+   - Solution: Pre-cached 1-hop neighbors for O(1) context
+
+---
+
+## [0.6.48] - 2025-12-17
+
+### Clearer Product Definition
+
+#### Added "What Is This?" Section
+New section at the very top of README explaining:
+
+1. **rust-kgdb** = High-Performance RDF Database (Rust core)
+   - SPARQL 1.1 query engine (449ns lookups)
+   - GraphFrames, Datalog, HNSW embeddings
+
+2. **HyperMind Agent Framework** = AI agent layer (JavaScript)
+   - Natural language queries
+   - Schema auto-extraction
+   - Audit trail
+
+**Summary**: "A knowledge graph database with an AI agent layer on top."
+
+#### Fixed Misleading +14.3pp Claim
+- **Old (wrong)**: "HyperMind's +14.3pp comes from predicate resolver"
+- **New (correct)**: DSPy gets 14.3% WITHOUT schema due to structured output format
+
+**Fact check**: All frameworks achieve identical 71.4% WITH schema.
+
+---
+
 ## [0.6.47] - 2025-12-17
 
 ### Memory Retrieval Depth Benchmark Added

package/README.md

@@ -4,6 +4,51 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![W3C](https://img.shields.io/badge/W3C-SPARQL%201.1%20%7C%20RDF%201.2-blue)](https://www.w3.org/TR/sparql11-query/)
 
+## What Is This?
+
+**rust-kgdb** is two things in one package:
+
+1. **High-Performance RDF Database** (Rust core)
+   - SPARQL 1.1 query engine with 449ns lookup speed
+   - GraphFrames analytics (PageRank, connected components, motifs)
+   - Datalog reasoning engine
+   - HNSW vector embeddings for similarity search
+   - 35x faster than RDFox, 25% less memory
+
+2. **HyperMind Agent Framework** (JavaScript layer)
+   - AI agents that query the database using natural language
+   - Schema auto-extraction from your data
+   - Typed tools that prevent hallucination
+   - Audit trail for every answer
+
+**Think of it as**: A knowledge graph database with an AI agent layer on top. The database provides ground truth. The agent layer makes it accessible via natural language.
+
+---
+
+## Core Concepts: What We Bring and Why
+
+### 1. Schema-Aware Query Generation
+**Problem**: LLMs generate SPARQL with made-up predicates (`?person :fakeProperty ?value`).
+**Solution**: We auto-extract your schema and inject it into prompts. The LLM can ONLY reference predicates that actually exist in your data.
+
+### 2. Built-in Database (Not BYODB)
+**Problem**: LangChain/DSPy generate queries, but you need to find a database to run them.
+**Solution**: rust-kgdb IS the database. Generate query → Execute query → Return results. All in one package.
+
+### 3. Audit Trail (Provenance)
+**Problem**: LLM says "Provider P001 is suspicious" - where did that come from?
+**Solution**: Every answer includes a reasoning trace showing which SPARQL queries ran, which rules matched, and what data was found.
+
+### 4. Deterministic Execution
+**Problem**: Ask the same question twice, get different answers.
+**Solution**: Same input → Same query → Same database → Same result → Same hash. Reproducible for compliance.
+
+### 5. ARCADE 1-Hop Cache
+**Problem**: Embedding lookups are slow when you need neighborhood context.
+**Solution**: Pre-cache 1-hop neighbors. When you find "Provider", instantly know its outgoing predicates (hasRiskScore, hasClaim) without another query.
+
+---
+
 ## AI Answers You Can Trust
 
 **The Problem**: LLMs hallucinate. They make up facts, invent data, and confidently state falsehoods. In regulated industries (finance, healthcare, legal), this is not just annoying—it's a liability.
@@ -200,8 +245,8 @@ Based on academic benchmarks: MemQ (arXiv 2503.05193), mKGQAgent (Text2SPARQL 20
 │  HONEST TRUTH: Schema injection improves ALL frameworks equally.            │
 │  Any framework + schema context achieves ~71% accuracy.                     │
 │                                                                             │
-│  HyperMind's +14.3pp comes from predicate resolver, but this is             │
-│  incremental improvement, not a fundamental breakthrough.                   │
+│  NOTE: DSPy gets 14.3% WITHOUT schema (vs 0% for others) due to            │
+│  its structured output format. With schema, all converge to 71.4%.          │
 │                                                                             │
 │  OUR REAL VALUE: We include the database. Others don't.                     │
 │  - LangChain generates SPARQL → you need to find a database                 │

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.6.47",
+  "version": "0.6.49",
   "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",