rust-kgdb 0.6.9 → 0.6.10

package/examples/fraud-detection-agent.js

@@ -68,6 +68,56 @@ const {
 // ═══════════════════════════════════════════════════════════════════════════════
 // CONFIGURATION - Professional Design Pattern: Configuration Object
 // ═══════════════════════════════════════════════════════════════════════════════
+//
+// ┌─────────────────────────────────────────────────────────────────────────────┐
+// │ KNOWLEDGE GRAPH STORAGE MODES                                               │
+// └─────────────────────────────────────────────────────────────────────────────┘
+//
+// MODE 1: IN-MEMORY (Default - Used in this example)
+// ──────────────────────────────────────────────────
+//   const db = new GraphDB('http://example.org/')  // In-memory, zero config
+//   - Storage: RAM only (HashMap-based SPOC indexes)
+//   - Performance: 2.78µs lookups, 146K triples/sec insert
+//   - Persistence: None (data lost on restart)
+//   - Use case: Development, testing, ephemeral workloads
+//
+// MODE 2: ENDPOINT (Distributed Cluster)
+// ──────────────────────────────────────
+//   const agent = await HyperMindAgent.spawn({
+//     endpoint: 'http://rust-kgdb-coordinator:8080',  // K8s service
+//     ...
+//   })
+//   - Storage: HDRF-partitioned across executors
+//   - Persistence: RocksDB/LMDB per executor
+//   - Consensus: Raft for distributed writes
+//   - Use case: Production, 1B+ triples
+//
+// ┌─────────────────────────────────────────────────────────────────────────────┐
+// │ DEFAULT SETTINGS (When not specified)                                       │
+// └─────────────────────────────────────────────────────────────────────────────┘
+//
+// KG Defaults:
+//   storage: 'inmemory'           // Not 'rocksdb' or 'lmdb'
+//   endpoint: null                // Local mode, no network
+//   graphUri: null                // Default graph (not named graph)
+//
+// Memory Layer Defaults:
+//   working.maxSize: 1MB          // Current task context
+//   episodic.retentionDays: 30    // Conversation history
+//   longTerm: db                  // KG as long-term memory (same instance!)
+//   weights: { recency: 0.3, relevance: 0.5, importance: 0.2 }
+//
+// Sandbox Defaults (when .withSandbox() NOT called):
+//   sandbox: null                 // NO SANDBOX - full access to all tools
+//   ⚠️  WARNING: Without sandbox, agent has unrestricted capabilities
+//   ⚠️  Always use .withSandbox() in production for security
+//
+// Governance Defaults:
+//   maxExecutionTimeMs: 60000     // 60 second timeout
+//   maxToolCalls: 100             // Rate limiting
+//   auditLevel: 'basic'           // Not 'full'
+//
+// ═══════════════════════════════════════════════════════════════════════════════
 
 const CONFIG = {
   // LLM Configuration
@@ -79,15 +129,48 @@ const CONFIG = {
   },
 
   // Knowledge Graph Configuration
+  // ─────────────────────────────
+  // This example uses IN-MEMORY mode for simplicity.
+  // For production, use endpoint mode with distributed cluster.
   kg: {
+    // Storage mode: 'inmemory' (default) | 'rocksdb' | 'lmdb' | 'endpoint'
+    storage: 'inmemory',
+
+    // Base URI for all entities (required)
     baseUri: 'http://insurance.org/fraud-detection',
-    graphUri: 'http://insurance.org/fraud-kb'
+
+    // Named graph URI (optional, null = default graph)
+    graphUri: 'http://insurance.org/fraud-kb',
+
+    // Endpoint for distributed mode (null = local mode)
+    // endpoint: 'http://rust-kgdb-coordinator:8080',  // Uncomment for cluster
+    endpoint: null
   },
 
   // Embedding Configuration (384-dim for compatibility)
   embeddings: {
     dimensions: 384,
-    similarityThreshold: 0.7
+    similarityThreshold: 0.7,
+    // Provider: 'mock' (default) | 'openai' | 'ollama' | 'anthropic'
+    provider: 'mock'
+  },
+
+  // Memory Layer Configuration (v0.5.13+)
+  // ─────────────────────────────────────
+  memory: {
+    working: {
+      maxSize: 1024 * 1024  // 1MB working memory for current task
+    },
+    episodic: {
+      retentionDays: 30,    // Keep 30 days of conversation history
+      maxEpisodes: 1000     // Cap total episodes
+    },
+    // longTerm: db          // Set after db initialization (uses same KG!)
+    weights: {
+      recency: 0.3,         // How recent (0.995^hours decay)
+      relevance: 0.5,       // Semantic similarity to query
+      importance: 0.2       // Access frequency
+    }
   },
 
   // Agent Configuration
@@ -96,6 +179,19 @@ const CONFIG = {
     tools: ['kg.sparql.query', 'kg.motif.find', 'kg.datalog.apply', 'kg.embeddings.search'],
     maxIterations: 10,
     tracingEnabled: true
+  },
+
+  // Sandbox Configuration (v0.6.7+)
+  // ────────────────────────────────
+  // ⚠️  IMPORTANT: If sandbox is null/undefined, agent has FULL ACCESS
+  // Always define sandbox in production for capability-based security
+  sandbox: {
+    capabilities: ['ReadKG', 'WriteKG', 'ExecuteTool', 'UseEmbeddings'],
+    fuelLimit: 1_000_000,    // Gas limit (prevents infinite loops)
+    maxExecTime: 30_000,     // 30 second timeout
+    maxMemory: 64 * 1024 * 1024,  // 64MB memory limit
+    allowedNamespaces: ['http://insurance.org/'],
+    auditLevel: 'full'       // 'none' | 'basic' | 'full'
   }
 }
 
@@ -321,18 +417,44 @@ async function main() {
   // ───────────────────────────────────────────────────────────────────────────
   // PHASE 1: Initialize Knowledge Graph
   // ───────────────────────────────────────────────────────────────────────────
+  //
+  // KG Storage Modes:
+  // ─────────────────
+  // 1. IN-MEMORY (this example):
+  //    const db = new GraphDB(baseUri)  // No config = in-memory
+  //
+  // 2. PERSISTENT (RocksDB):
+  //    const db = new GraphDB(baseUri, { storage: 'rocksdb', path: '/data/kg' })
+  //
+  // 3. DISTRIBUTED (Cluster endpoint):
+  //    const agent = await HyperMindAgent.spawn({
+  //      endpoint: 'http://rust-kgdb-coordinator:8080',
+  //      name: 'fraud-detector',
+  //      ...
+  //    })
+  //    // Agent handles KG operations via gRPC to cluster
+  //
+  // ───────────────────────────────────────────────────────────────────────────
 
   console.log('┌─ PHASE 1: Knowledge Graph Initialization ───────────────────────────────┐')
-  console.log('│  Tool: kg.sparql.load                                                   │')
-  console.log('│  Type: TTL → Graph                                                      │')
+  console.log('│  Mode: IN-MEMORY (HashMap-based SPOC indexes)                           │')
+  console.log('│  Performance: 2.78µs lookups | 24 bytes/triple | Zero-copy              │')
   console.log('└─────────────────────────────────────────────────────────────────────────┘')
 
+  // Initialize KG - IN-MEMORY mode (default when no storage config provided)
+  // For production with persistence: new GraphDB(baseUri, { storage: 'rocksdb', path: '/data' })
   const db = new GraphDB(CONFIG.kg.baseUri)
+
+  // Load TTL data into named graph
+  // null = default graph, string = named graph URI
   db.loadTtl(FRAUD_ONTOLOGY, CONFIG.kg.graphUri)
   const tripleCount = db.countTriples()
 
-  console.log(`  ✓ Knowledge Graph loaded: ${tripleCount} triples`)
+  console.log(`  ✓ Storage Mode: ${CONFIG.kg.storage} (data in RAM, lost on restart)`)
+  console.log(`  ✓ Base URI: ${CONFIG.kg.baseUri}`)
   console.log(`  ✓ Graph URI: ${CONFIG.kg.graphUri}`)
+  console.log(`  ✓ Triples Loaded: ${tripleCount}`)
+  console.log(`  ✓ Endpoint: ${CONFIG.kg.endpoint || 'null (local mode, no network)'}`)
   console.log()
 
   // ───────────────────────────────────────────────────────────────────────────

package/examples/underwriting-agent.js

@@ -62,6 +62,56 @@ const {
 // ═══════════════════════════════════════════════════════════════════════════
 // CONFIGURATION
 // ═══════════════════════════════════════════════════════════════════════════
+//
+// ┌─────────────────────────────────────────────────────────────────────────────┐
+// │ KNOWLEDGE GRAPH STORAGE MODES                                               │
+// └─────────────────────────────────────────────────────────────────────────────┘
+//
+// MODE 1: IN-MEMORY (Default - Used in this example)
+// ──────────────────────────────────────────────────
+//   const db = new GraphDB('http://example.org/')  // In-memory, zero config
+//   - Storage: RAM only (HashMap-based SPOC indexes)
+//   - Performance: 2.78µs lookups, 146K triples/sec insert
+//   - Persistence: None (data lost on restart)
+//   - Use case: Development, testing, ephemeral workloads
+//
+// MODE 2: ENDPOINT (Distributed Cluster)
+// ──────────────────────────────────────
+//   const agent = await HyperMindAgent.spawn({
+//     endpoint: 'http://rust-kgdb-coordinator:8080',  // K8s service
+//     ...
+//   })
+//   - Storage: HDRF-partitioned across executors
+//   - Persistence: RocksDB/LMDB per executor
+//   - Consensus: Raft for distributed writes
+//   - Use case: Production, 1B+ triples
+//
+// ┌─────────────────────────────────────────────────────────────────────────────┐
+// │ DEFAULT SETTINGS (When not specified)                                       │
+// └─────────────────────────────────────────────────────────────────────────────┘
+//
+// KG Defaults:
+//   storage: 'inmemory'           // Not 'rocksdb' or 'lmdb'
+//   endpoint: null                // Local mode, no network
+//   graphUri: null                // Default graph (not named graph)
+//
+// Memory Layer Defaults:
+//   working.maxSize: 1MB          // Current task context
+//   episodic.retentionDays: 30    // Conversation history
+//   longTerm: db                  // KG as long-term memory (same instance!)
+//   weights: { recency: 0.3, relevance: 0.5, importance: 0.2 }
+//
+// Sandbox Defaults (when .withSandbox() NOT called):
+//   sandbox: null                 // NO SANDBOX - full access to all tools
+//   ⚠️  WARNING: Without sandbox, agent has unrestricted capabilities
+//   ⚠️  Always use .withSandbox() in production for security
+//
+// Governance Defaults:
+//   maxExecutionTimeMs: 60000     // 60 second timeout
+//   maxToolCalls: 100             // Rate limiting
+//   auditLevel: 'basic'           // Not 'full'
+//
+// ═══════════════════════════════════════════════════════════════════════════
 
 const MODEL = process.argv.includes('--model')
   ? process.argv[process.argv.indexOf('--model') + 1]
@@ -69,6 +119,51 @@ const MODEL = process.argv.includes('--model')
   : process.env.OPENAI_API_KEY ? 'gpt-4o'
   : 'mock'
 
+// Full configuration object with all settings
+const CONFIG = {
+  // LLM Configuration
+  llm: {
+    model: MODEL,
+    maxTokens: 1024,
+    temperature: 0.1
+  },
+
+  // Knowledge Graph Configuration
+  // ─────────────────────────────
+  // This example uses IN-MEMORY mode for simplicity.
+  // For production, use endpoint mode with distributed cluster.
+  kg: {
+    storage: 'inmemory',          // 'inmemory' | 'rocksdb' | 'lmdb' | 'endpoint'
+    baseUri: 'http://underwriting.org/',
+    graphUri: 'http://underwriting.org/kb',
+    endpoint: null                // Set to cluster URL for distributed mode
+  },
+
+  // Embedding Configuration
+  embeddings: {
+    dimensions: 384,
+    similarityThreshold: 0.7,
+    provider: 'mock'              // 'mock' | 'openai' | 'ollama' | 'anthropic'
+  },
+
+  // Memory Layer Configuration (v0.5.13+)
+  memory: {
+    working: { maxSize: 1024 * 1024 },  // 1MB
+    episodic: { retentionDays: 30, maxEpisodes: 1000 },
+    weights: { recency: 0.3, relevance: 0.5, importance: 0.2 }
+  },
+
+  // Sandbox Configuration (v0.6.7+)
+  // ⚠️  If null, agent has FULL ACCESS - always set in production
+  sandbox: {
+    capabilities: ['ReadKG', 'ExecuteTool', 'UseEmbeddings', 'AccessMemory'],
+    fuelLimit: 500_000,
+    maxExecTime: 30_000,
+    maxMemory: 64 * 1024 * 1024,
+    auditLevel: 'full'
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // UNDERWRITING KNOWLEDGE BASE (ISO/NAIC-Informed Data)
 // ═══════════════════════════════════════════════════════════════════════════

package/package.json

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