rust-kgdb 0.3.9 → 0.3.10

package/README.md

@@ -581,42 +581,143 @@ 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
+
+**HyperMind agents do NOT use embeddings for query generation.** Embeddings are a separate feature for semantic similarity search:
+
+```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
 ```
 
+| 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) |
+
 ### Architecture Overview
 
 ```

package/package.json

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