rust-kgdb 0.6.3 → 0.6.5

package/README.md

@@ -205,33 +205,48 @@ agent.chat("What fraud patterns did we find with Provider P001?")
 // Cost: Re-run entire fraud detection pipeline ($5 in API calls, 30 seconds)
 ```
 
-**With Memory Hypergraph** (rust-kgdb):
+**With Memory Hypergraph** (rust-kgdb HyperMind Framework):
 ```javascript
-// Memories are automatically linked to KG entities
-const memories = await agent.recall("Provider P001 fraud", 10)
-// Returns: Episodes 001, 002, 003 - all linked to Provider:P001 in KG
+// HyperMind API: Recall memories with KG context (typed, not raw SPARQL)
+const enrichedMemories = await agent.recallWithKG({
+  query: "Provider P001 fraud",
+  kgFilter: { predicate: ":amount", operator: ">", value: 25000 },
+  limit: 10
+})
 
-// Even better: SPARQL traverses BOTH memory and KG
-const results = db.querySelect(`
-  PREFIX am: <https://gonnect.ai/ontology/agent-memory#>
-  PREFIX : <http://insurance.org/>
-
-  SELECT ?episode ?finding ?claimAmount WHERE {
-    # Search memory graph
-    GRAPH <https://gonnect.ai/memory/> {
-      ?episode a am:Episode ;
-               am:prompt ?finding .
-      ?edge am:source ?episode ;
-            am:target ?provider .
-    }
-    # Join with knowledge graph
-    ?claim :provider ?provider ;
-           :amount ?claimAmount .
-    FILTER(?claimAmount > 25000)
+// Returns typed results:
+// {
+//   episode: "Episode:001",
+//   finding: "Fraud ring detected in Provider P001",
+//   kgContext: {
+//     provider: "Provider:P001",
+//     claims: [{ id: "Claim:C123", amount: 50000 }],
+//     riskScore: 0.87
+//   },
+//   semanticHash: "semhash:fraud-provider-p001-ring-detection"
+// }
+
+// Framework generates optimized SPARQL internally:
+// - Joins memory graph with KG automatically
+// - Applies semantic hashing for deduplication
+// - Returns typed objects, not raw bindings
+```
+
+**Under the hood**, HyperMind generates the SPARQL:
+```sparql
+PREFIX am: <https://gonnect.ai/ontology/agent-memory#>
+PREFIX : <http://insurance.org/>
+
+SELECT ?episode ?finding ?claimAmount WHERE {
+  GRAPH <https://gonnect.ai/memory/> {
+    ?episode a am:Episode ; am:prompt ?finding .
+    ?edge am:source ?episode ; am:target ?provider .
   }
-`)
-// Returns: Episode findings + actual claim data - in ONE query!
+  ?claim :provider ?provider ; :amount ?claimAmount .
+  FILTER(?claimAmount > 25000)
+}
 ```
+*You never write this - the typed API builds it for you.*
 
 ### Rolling Context Window
 

package/examples/core-concepts-demo.ts

@@ -18,9 +18,12 @@
 
 import {
     GraphDB,
-    DatalogEngine,
+    DatalogProgram,
+    evaluateDatalog,
+    queryDatalog,
     EmbeddingService,
     GraphFrame,
+    HyperMindAgent,
 } from 'rust-kgdb';
 
 // =============================================================================
@@ -242,46 +245,53 @@ function demoDatalogReasoning(): void {
     console.log('='.repeat(70));
     console.log();
 
-    const engine = new DatalogEngine();
+    const program = new DatalogProgram();
 
-    // Add facts
+    // Add facts using JSON format
     console.log('  Facts (parent relationship):');
-    engine.addFact('parent', ['alice', 'bob']);
-    engine.addFact('parent', ['bob', 'charlie']);
-    engine.addFact('parent', ['charlie', 'david']);
+    program.addFact(JSON.stringify({ predicate: 'parent', terms: ['alice', 'bob'] }));
+    program.addFact(JSON.stringify({ predicate: 'parent', terms: ['bob', 'charlie'] }));
+    program.addFact(JSON.stringify({ predicate: 'parent', terms: ['charlie', 'david'] }));
     console.log('    parent(alice, bob)');
     console.log('    parent(bob, charlie)');
     console.log('    parent(charlie, david)');
+    console.log(`    Total facts: ${program.factCount()}`);
     console.log();
 
-    // Add recursive rules
+    // Add recursive rules using JSON format
     console.log('  Rules (transitive closure):');
     console.log('    ancestor(X, Y) :- parent(X, Y)              % base case');
     console.log('    ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z)  % recursive');
     console.log();
 
-    // Base case
-    engine.addRule('ancestor', ['X', 'Y'], [
-        { predicate: 'parent', args: ['X', 'Y'] }
-    ]);
+    // Base case: ancestor(X, Y) :- parent(X, Y)
+    program.addRule(JSON.stringify({
+        head: { predicate: 'ancestor', terms: ['X', 'Y'] },
+        body: [{ predicate: 'parent', terms: ['X', 'Y'] }]
+    }));
 
-    // Recursive case
-    engine.addRule('ancestor', ['X', 'Z'], [
-        { predicate: 'parent', args: ['X', 'Y'] },
-        { predicate: 'ancestor', args: ['Y', 'Z'] }
-    ]);
+    // Recursive case: ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z)
+    program.addRule(JSON.stringify({
+        head: { predicate: 'ancestor', terms: ['X', 'Z'] },
+        body: [
+            { predicate: 'parent', terms: ['X', 'Y'] },
+            { predicate: 'ancestor', terms: ['Y', 'Z'] }
+        ]
+    }));
 
-    // Evaluate
-    const iterations = engine.evaluateSemiNaive();
-    console.log(`  Semi-naive evaluation completed in ${iterations} iterations`);
+    // Evaluate using semi-naive algorithm
+    const evalResult = evaluateDatalog(program);
+    console.log(`  Semi-naive evaluation completed`);
+    console.log(`  Result: ${evalResult}`);
     console.log();
 
-    // Query
-    const results = engine.query('ancestor', ['alice', '?descendant']);
-    console.log('  Query: ancestor(alice, ?descendant)');
+    // Query ancestors
+    const results = queryDatalog(program, 'ancestor');
+    const parsed = JSON.parse(results);
+    console.log('  Query: ancestor(?who, ?descendant)');
     console.log('  Results:');
-    for (const r of results) {
-        console.log(`    - alice is ancestor of ${r.descendant}`);
+    for (const r of parsed) {
+        console.log(`    - ${r.terms[0]} is ancestor of ${r.terms[1]}`);
     }
     console.log();
 }
@@ -418,23 +428,28 @@ function demoHyperMindAgents(): void {
     console.log('  Agent Creation (TypeScript):');
     console.log('  ------------------------------');
     console.log(`
-    import { spawn, AgentSpec, Model } from 'rust-kgdb';
+    import { HyperMindAgent } from 'rust-kgdb';
 
-    const agent = await spawn({
+    // Spawn a HyperMind agent with typed tools
+    const agent = await HyperMindAgent.spawn({
         name: 'fraud-detector',
-        model: Model.Claude('claude-3-opus'),
+        model: 'claude-sonnet-4',  // or 'gpt-4o', 'claude-opus-4', 'mock'
         tools: [
-            'kg.sparql.query',
-            'kg.motif.find',
-            'kg.datalog.apply',
+            'kg.sparql.query',     // Query -> BindingSet
+            'kg.motif.find',       // Graph -> PatternSet
+            'kg.datalog.apply',    // Rules -> InferredFacts
         ],
-        maxIterations: 10,
-        tracingEnabled: true,
-        wasmSandbox: true,
+        endpoint: 'http://localhost:30080',  // K8s cluster endpoint
+        tracing: true,
     });
 
-    const result = await agent.call('Find circular payments');
-    await agent.exportTrace('audit.json');
+    // Execute with natural language
+    const result = await agent.call('Find circular payment patterns');
+    console.log(result.sparql);   // Generated SPARQL
+    console.log(result.results);  // Query results
+
+    // Get execution trace for audit
+    const trace = agent.getTrace();
     `);
     console.log();
 }