rust-kgdb 0.3.10 → 0.3.11

package/README.md

@@ -574,6 +574,30 @@ console.log('Bipartite(3,4):', bp34.vertexCount(), 'vertices,', bp34.edgeCount()
 
 ## 7. HyperMind Agentic Framework (Neuro-Symbolic AI)
 
+### ⚡ TL;DR: What is HyperMind?
+
+**HyperMind converts natural language questions into SPARQL queries.**
+
+```typescript
+// Input:  "Find all professors"
+// Output: "SELECT ?x WHERE { ?x a ub:Professor }"
+```
+
+**NOT to be confused with:**
+- ❌ **EmbeddingService** - That's for semantic similarity search (different feature)
+- ❌ **GraphDB** - That's for direct SPARQL queries (no natural language)
+
+### Quick Start: Create an Agent in 3 Lines
+
+```typescript
+const { HyperMindAgent } = require('rust-kgdb')
+
+const agent = await HyperMindAgent.spawn({ model: 'mock', endpoint: 'http://localhost:30080' })
+const result = await agent.call('Find all professors')  // → SPARQL query + results
+```
+
+---
+
 HyperMind is a **production-grade neuro-symbolic agentic framework** built on rust-kgdb that combines:
 
 - **Type Theory**: Compile-time safety with typed tool contracts
@@ -692,31 +716,55 @@ console.log(`Success: ${stats.syntaxSuccess}/${stats.totalTests}`)  // 12/12
 console.log(`Latency: ${stats.avgLatencyMs.toFixed(1)}ms`)          // ~6.58ms
 ```
 
-### Important: Embeddings Are Separate
+### ⚠️ Important: Embeddings Are SEPARATE from HyperMind
 
-**HyperMind agents do NOT use embeddings for query generation.** Embeddings are a separate feature for semantic similarity search:
+```
+┌───────────────────────────────────────────────────────────────────────────────┐
+│  COMMON CONFUSION: These are TWO DIFFERENT FEATURES                           │
+├───────────────────────────────────────────────────────────────────────────────┤
+│                                                                               │
+│  HyperMindAgent                        EmbeddingService                       │
+│  ─────────────────                     ─────────────────                      │
+│  • Natural Language → SPARQL           • Text → Vector embeddings             │
+│  • "Find professors" → SQL-like query  • "professor" → [0.1, 0.2, ...]        │
+│  • Returns database results            • Returns similar items                │
+│  • NO embeddings used internally       • ALL about embeddings                 │
+│                                                                               │
+│  Use HyperMind when:                   Use Embeddings when:                   │
+│  "I want to query my database          "I want to find semantically           │
+│   using natural language"               similar items"                        │
+│                                                                               │
+└───────────────────────────────────────────────────────────────────────────────┘
+```
 
 ```typescript
-const { EmbeddingService, GraphDB } = require('rust-kgdb')
-
-// Embeddings: For semantic similarity search (SEPARATE from HyperMind)
-const embeddings = new EmbeddingService({ provider: 'mock', dimensions: 384 })
-embeddings.addText('professor', 'A teacher at a university')
-embeddings.addText('student', 'Someone who studies at a university')
-const similar = embeddings.findSimilar('teacher', 5)  // Finds "professor"
-
-// HyperMind: For natural language to SPARQL (NO embeddings used)
-const agent = await HyperMindAgent.spawn({ model: 'mock', ... })
-const result = await agent.call('Find professors')  // Generates SPARQL query
+const { HyperMindAgent, EmbeddingService, GraphDB } = require('rust-kgdb')
+
+// ──────────────────────────────────────────────────────────────────────────────
+// HYPERMIND: Natural language → SPARQL queries (NO embeddings)
+// ──────────────────────────────────────────────────────────────────────────────
+const agent = await HyperMindAgent.spawn({ model: 'mock', endpoint: 'http://localhost:30080' })
+const result = await agent.call('Find all professors')
+// result.sparql = "SELECT ?x WHERE { ?x a ub:Professor }"
+// result.results = [{ x: "http://university.edu/prof1" }, ...]
+
+// ──────────────────────────────────────────────────────────────────────────────
+// EMBEDDINGS: Semantic similarity search (COMPLETELY SEPARATE)
+// ──────────────────────────────────────────────────────────────────────────────
+const embeddings = new EmbeddingService()
+embeddings.storeVector('professor', [0.1, 0.2, 0.3, ...])  // 384-dim vector
+embeddings.storeVector('teacher', [0.11, 0.21, 0.31, ...])
+const similar = embeddings.findSimilar('professor', 5)  // Finds "teacher" by cosine similarity
 ```
 
-| Feature | HyperMind Agent | Embedding Service |
-|---------|-----------------|-------------------|
-| **Purpose** | NL → SPARQL queries | Semantic similarity |
-| **Input** | Natural language question | Text to embed |
-| **Output** | SPARQL query + results | Similar items |
-| **Uses embeddings?** | No | Yes |
-| **Requires API key?** | Only for LLM mode | No (mock available) |
+| Feature | HyperMindAgent | EmbeddingService |
+|---------|----------------|------------------|
+| **What it does** | NL → SPARQL queries | Semantic similarity search |
+| **Input** | "Find all professors" | Text or vectors |
+| **Output** | SPARQL query + results | Similar items list |
+| **Uses embeddings?** | ❌ **NO** | ✅ Yes |
+| **Uses LLM?** | ✅ Yes (or mock) | ❌ No |
+| **Requires API key?** | Only for LLM mode | No |
 
 ### Architecture Overview
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "High-performance RDF/SPARQL database with GraphFrames analytics, vector embeddings, Datalog reasoning, Pregel BSP processing, and HyperMind neuro-symbolic agentic framework",
   "main": "index.js",
   "types": "index.d.ts",