rust-kgdb 0.5.10 → 0.5.12

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
 
+## [0.5.12] - 2025-12-15
+
+### Benchmark Section Cleanup
+
+- Removed internal Cargo/Rust implementation details from benchmark documentation
+- Simplified to focus on WHAT (metrics), WHY (value), and HOW (user-facing commands)
+- Kept key numbers: 2.78µs lookups, 24 bytes/triple, 86.4% accuracy
+- Removed: rustc commands, cargo bench paths, crate paths
+- User-facing: `node hypermind-benchmark.js` for accuracy comparison
+
+## [0.5.11] - 2025-12-15
+
+### Documentation Clarification
+
+- Clarified that embedding providers (OpenAI, Voyage AI) are third-party libraries, not built into rust-kgdb
+- Updated examples to show `fetch` API for Voyage AI instead of non-existent SDK
+- Added "bring your own embeddings" messaging to make provider abstraction clear
+- rust-kgdb's EmbeddingService stores/searches vectors; users provide embeddings from their preferred provider
+
 ## [0.5.10] - 2025-12-15
 
 ### Documentation Cleanup

package/README.md

@@ -131,68 +131,25 @@ We don't make claims we can't prove. All measurements use **publicly available,
 - **SP2Bench** - DBLP-based SPARQL performance benchmark
 - **W3C SPARQL 1.1 Conformance Suite** - Official W3C test cases
 
-**Test Environment:**
-- Hardware: Apple Silicon M-series (ARM64), Intel x64
-- Dataset: LUBM(1) - 3,272 triples, LUBM(10) - 32K triples, LUBM(100) - 327K triples
-- Tool: Criterion.rs statistical benchmarking (10,000+ iterations per measurement)
-- Comparison: Apache Jena 4.x, RDFox 7.x under identical conditions
-
-| Metric | Value | Context |
-|--------|-------|---------|
+| Metric | Value | Why It Matters |
+|--------|-------|----------------|
 | **Lookup Latency** | 2.78 µs | 35x faster than RDFox |
 | **Memory per Triple** | 24 bytes | 25% more efficient than RDFox |
-| **Bulk Insert** | 146K triples/sec | Competitive with commercial systems |
-| **SPARQL Accuracy** | 86.4% | vs 0% vanilla LLM (LUBM Q1-Q14) |
+| **Bulk Insert** | 146K triples/sec | Production-ready throughput |
+| **SPARQL Accuracy** | 86.4% | vs 0% vanilla LLM (LUBM benchmark) |
 | **W3C Compliance** | 100% | Full SPARQL 1.1 + RDF 1.2 |
-| **SIMD Speedup** | 44.5% avg | Range: 9-77% depending on query |
-| **WCOJ Joins** | O(N^(ρ/2)) | Worst-case optimal guaranteed |
-| **Ontology Support** | RDFS + OWL 2 RL | Full reasoning engine |
-| **Test Coverage** | 945+ tests | Production certified |
-
-**Reproducibility:** All benchmarks at `crates/storage/benches/` and `crates/hypergraph/benches/`. Run with `cargo bench --workspace`.
-
-### Benchmark Methodology
-
-**How we measure performance:**
-
-1. **LUBM Data Generation**
-   ```bash
-   # Generate test data (matches official Java UBA generator)
-   rustc tools/lubm_generator.rs -O -o tools/lubm_generator
-   ./tools/lubm_generator 1 /tmp/lubm_1.nt    # 3,272 triples
-   ./tools/lubm_generator 10 /tmp/lubm_10.nt  # ~32K triples
-   ```
-
-2. **Storage Benchmarks**
-   ```bash
-   # Run Criterion benchmarks (statistical analysis, 10K+ samples)
-   cargo bench --package storage --bench triple_store_benchmark
-
-   # Results include:
-   # - Mean, median, standard deviation
-   # - Outlier detection
-   # - Comparison vs baseline
-   ```
-
-3. **HyperMind Agent Accuracy**
-   ```bash
-   # Run LUBM benchmark comparing Vanilla LLM vs HyperMind
-   node hypermind-benchmark.js
-
-   # Tests 12 queries (Easy: 3, Medium: 5, Hard: 4)
-   # Measures: Syntax validity, execution success, latency
-   ```
-
-4. **Hardware Requirements**
-   - Minimum: 4GB RAM, any x64/ARM64 CPU
-   - Recommended: 8GB+ RAM, Apple Silicon or modern x64
-   - Benchmarks run on: M2 MacBook Pro (baseline measurements)
-
-5. **Fair Comparison Conditions**
-   - All systems tested with identical LUBM datasets
-   - Same SPARQL queries across all systems
-   - Cold-start measurements (no warm cache)
-   - 10,000+ iterations per measurement for statistical significance
+
+### How We Measured
+
+- **Dataset**: LUBM benchmark (industry standard since 2005)
+- **Hardware**: Apple Silicon M2 MacBook Pro
+- **Methodology**: 10,000+ iterations, cold-start, statistical analysis
+- **Comparison**: Apache Jena 4.x, RDFox 7.x under identical conditions
+
+**Try it yourself:**
+```bash
+node hypermind-benchmark.js  # Compare HyperMind vs Vanilla LLM accuracy
+```
 
 ---
 
@@ -309,11 +266,13 @@ const voteResults = service.findSimilarComposite('CLM001', 10, 0.7, 'voting') //
 
 ### Provider Configuration
 
-Configure your embedding providers with API keys:
+rust-kgdb's `EmbeddingService` stores and searches vectors - you bring your own embeddings from any provider. Here are examples using popular third-party libraries:
 
 ```javascript
-// Example: Using OpenAI embeddings
-const { OpenAI } = require('openai')
+// ============================================================
+// EXAMPLE: Using OpenAI embeddings (requires: npm install openai)
+// ============================================================
+const { OpenAI } = require('openai')  // Third-party library
 const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
 
 async function getOpenAIEmbedding(text) {
@@ -325,17 +284,31 @@ async function getOpenAIEmbedding(text) {
   return response.data[0].embedding
 }
 
-// Example: Using Anthropic (via their embedding partner)
-// Note: Anthropic doesn't provide embeddings directly; use Voyage AI
-const { VoyageAIClient } = require('voyageai')
-const voyage = new VoyageAIClient({ apiKey: process.env.VOYAGE_API_KEY })
-
+// ============================================================
+// EXAMPLE: Using Voyage AI (requires: npm install voyageai)
+// Note: Anthropic recommends Voyage AI for embeddings
+// ============================================================
 async function getVoyageEmbedding(text) {
-  const response = await voyage.embed({
-    input: text,
-    model: 'voyage-2'
+  // Using fetch directly (no SDK required)
+  const response = await fetch('https://api.voyageai.com/v1/embeddings', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${process.env.VOYAGE_API_KEY}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ input: text, model: 'voyage-2' })
   })
-  return response.embeddings[0].slice(0, 384)  // Truncate to 384-dim
+  const data = await response.json()
+  return data.data[0].embedding.slice(0, 384)  // Truncate to 384-dim
+}
+
+// ============================================================
+// EXAMPLE: Mock embeddings for testing (no external deps)
+// ============================================================
+function getMockEmbedding(text) {
+  return new Array(384).fill(0).map((_, i) =>
+    Math.sin(text.charCodeAt(i % text.length) * 0.1) * 0.5 + 0.5
+  )
 }
 ```
 
@@ -1224,11 +1197,12 @@ const db = new GraphDB('http://insurance.org/fraud-kb')
 const embeddings = new EmbeddingService()
 
 // ============================================================
-// STEP 3: Configure Embedding Provider
+// STEP 3: Configure Embedding Provider (bring your own)
 // ============================================================
 async function getEmbedding(text) {
   switch (EMBEDDING_PROVIDER) {
     case 'openai':
+      // Requires: npm install openai
       const { OpenAI } = require('openai')
       const openai = new OpenAI({ apiKey: OPENAI_API_KEY })
       const resp = await openai.embeddings.create({
@@ -1239,12 +1213,19 @@ async function getEmbedding(text) {
       return resp.data[0].embedding
 
     case 'voyage':
-      const { VoyageAIClient } = require('voyageai')
-      const voyage = new VoyageAIClient({ apiKey: VOYAGE_API_KEY })
-      const vResp = await voyage.embed({ input: text, model: 'voyage-2' })
-      return vResp.embeddings[0].slice(0, EMBEDDING_DIM)
+      // Using fetch directly (no SDK required)
+      const vResp = await fetch('https://api.voyageai.com/v1/embeddings', {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${VOYAGE_API_KEY}`,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({ input: text, model: 'voyage-2' })
+      })
+      const vData = await vResp.json()
+      return vData.data[0].embedding.slice(0, EMBEDDING_DIM)
 
-    default: // Mock embeddings for testing
+    default: // Mock embeddings for testing (no external deps)
       return new Array(EMBEDDING_DIM).fill(0).map((_, i) =>
         Math.sin(text.charCodeAt(i % text.length) * 0.1) * 0.5 + 0.5
       )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "description": "Production-grade Neuro-Symbolic AI Framework: +86.4% accuracy improvement over vanilla LLMs. High-performance knowledge graph (2.78µs lookups, 35x faster than RDFox). Features fraud detection, underwriting agents, WASM sandbox, type/category/proof theory, and W3C SPARQL 1.1 compliance.",
   "main": "index.js",
   "types": "index.d.ts",