rust-kgdb 0.3.9 → 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
@@ -581,42 +605,167 @@ HyperMind is a **production-grade neuro-symbolic agentic framework** built on ru
 - **Neural Planning**: LLM-based planning (Claude, GPT-4o)
 - **Symbolic Execution**: rust-kgdb knowledge graph operations
 
-### Quick Start: Create an Agent in 3 Lines
+### How It Works: Two Modes
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         HyperMind Agent Flow                                 │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   User: "Find all professors"                                               │
+│         │                                                                   │
+│         ▼                                                                   │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │  MODE 1: Mock (No API Keys)          MODE 2: LLM (With API Keys)    │   │
+│   │  ─────────────────────────────       ───────────────────────────    │   │
+│   │  • Pattern matches question          • Sends to Claude/GPT-4o       │   │
+│   │  • Returns pre-defined SPARQL        • LLM generates SPARQL         │   │
+│   │  • Instant (~6ms latency)            • ~2-6 second latency          │   │
+│   │  • For testing/benchmarks            • For production use           │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│         │                                                                   │
+│         ▼                                                                   │
+│   SPARQL Query: "SELECT ?x WHERE { ?x a ub:Professor }"                     │
+│         │                                                                   │
+│         ▼                                                                   │
+│   rust-kgdb Cluster: Executes query, returns results                        │
+│         │                                                                   │
+│         ▼                                                                   │
+│   Results: [{ bindings: { x: "http://..." } }, ...]                         │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Mode 1: Mock Mode (No API Keys Required)
+
+Use this for **testing, benchmarking, and development**. The mock model pattern-matches your question against 12 pre-defined LUBM queries:
 
 ```typescript
 const { HyperMindAgent } = require('rust-kgdb')
 
-// 1. Spawn an agent
+// Spawn agent with mock model - NO API KEYS NEEDED
 const agent = await HyperMindAgent.spawn({
-  name: 'university-explorer',
-  model: 'mock',                        // 'mock' | 'claude-sonnet-4' | 'gpt-4o'
-  tools: ['kg.sparql.query'],           // Available tools
-  endpoint: 'http://localhost:30080'    // rust-kgdb cluster endpoint
+  name: 'test-agent',
+  model: 'mock',                        // Uses pattern matching, not LLM
+  tools: ['kg.sparql.query'],
+  endpoint: 'http://localhost:30080'    // Your rust-kgdb endpoint
 })
 
-// 2. Ask natural language questions
+// Ask a question (pattern-matched to LUBM queries)
 const result = await agent.call('Find all professors in the database')
 
-// 3. Get results
-console.log(result.sparql)   // "PREFIX ub: <...> SELECT ?x WHERE { ?x a ub:Professor }"
-console.log(result.results)  // [{ bindings: { x: 'http://...' } }, ...]
 console.log(result.success)  // true
+console.log(result.sparql)   // "PREFIX ub: <...> SELECT ?x WHERE { ?x a ub:Professor }"
+console.log(result.results)  // Query results from your database
+```
+
+**Supported Mock Questions (12 LUBM patterns):**
+| Question Pattern | Generated SPARQL |
+|-----------------|------------------|
+| "Find all professors..." | `SELECT ?x WHERE { ?x a ub:Professor }` |
+| "List all graduate students" | `SELECT ?x WHERE { ?x a ub:GraduateStudent }` |
+| "How many courses..." | `SELECT (COUNT(?x) AS ?count) WHERE { ?x a ub:Course }` |
+| "Find students and their advisors" | `SELECT ?student ?advisor WHERE { ?student ub:advisor ?advisor }` |
+
+### Mode 2: LLM Mode (Requires API Keys)
+
+Use this for **production** with real LLM-powered query generation:
+
+```bash
+# Set environment variables BEFORE running your code
+export ANTHROPIC_API_KEY="sk-ant-api03-..."   # For Claude
+export OPENAI_API_KEY="sk-proj-..."            # For GPT-4o
+```
+
+```typescript
+const { HyperMindAgent } = require('rust-kgdb')
+
+// Spawn agent with Claude (requires ANTHROPIC_API_KEY)
+const agent = await HyperMindAgent.spawn({
+  name: 'prod-agent',
+  model: 'claude-sonnet-4',             // Real LLM - generates dynamic SPARQL
+  tools: ['kg.sparql.query', 'kg.motif.find'],
+  endpoint: 'http://localhost:30080'
+})
+
+// Any natural language question works (not limited to patterns)
+const result = await agent.call('Find professors who teach AI and have more than 5 publications')
+
+// LLM generates appropriate SPARQL dynamically
+console.log(result.sparql)  // Complex query generated by Claude
 ```
 
-### Run the Benchmark Suite
+**Supported LLM Models:**
+| Model | Environment Variable | Use Case |
+|-------|---------------------|----------|
+| `claude-sonnet-4` | `ANTHROPIC_API_KEY` | Best accuracy |
+| `gpt-4o` | `OPENAI_API_KEY` | Alternative |
+| `mock` | None | Testing only |
+
+### Run the Benchmark
 
 ```typescript
 const { runHyperMindBenchmark } = require('rust-kgdb')
 
-// Run 12 LUBM benchmark tests
+// Test with mock model (no API keys)
 const stats = await runHyperMindBenchmark('http://localhost:30080', 'mock', {
-  saveResults: true  // Saves to hypermind_benchmark_*.json
+  saveResults: true  // Saves JSON file with results
 })
 
-console.log(`Success Rate: ${stats.hypermindSyntaxRate}%`)  // 100%
-console.log(`Avg Latency: ${stats.avgLatencyMs}ms`)         // ~6.58ms
+console.log(`Success: ${stats.syntaxSuccess}/${stats.totalTests}`)  // 12/12
+console.log(`Latency: ${stats.avgLatencyMs.toFixed(1)}ms`)          // ~6.58ms
 ```
 
+### ⚠️ Important: Embeddings Are SEPARATE from HyperMind
+
+```
+┌───────────────────────────────────────────────────────────────────────────────┐
+│  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 { 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 | 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.9",
+  "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",