rust-kgdb 0.5.4 → 0.5.5

package/README.md

@@ -610,6 +610,521 @@ node examples/underwriting-agent.js
 
 ---
 
+## HyperMind Agent Design: A Complete Guide
+
+This section explains how to design production-grade AI agents using HyperMind's mathematical foundations. We'll walk through the complete architecture using our Fraud Detection and Underwriting agents as case studies.
+
+### The HyperMind Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         HYPERMIND FRAMEWORK                                  │
+│                                                                             │
+│  ┌───────────────┐   ┌───────────────┐   ┌───────────────┐                │
+│  │  TYPE THEORY  │   │   CATEGORY    │   │    PROOF      │                │
+│  │  (Hindley-    │   │    THEORY     │   │    THEORY     │                │
+│  │   Milner)     │   │  (Morphisms)  │   │  (Witnesses)  │                │
+│  └───────┬───────┘   └───────┬───────┘   └───────┬───────┘                │
+│          │                   │                   │                          │
+│          └─────────────┬─────┴───────────────────┘                          │
+│                        │                                                     │
+│  ┌─────────────────────▼─────────────────────────────────────────┐         │
+│  │                    TOOL REGISTRY                               │         │
+│  │  Every tool is a typed morphism: Input Type → Output Type     │         │
+│  │                                                                │         │
+│  │  kg.sparql.query   : SPARQLQuery    → BindingSet              │         │
+│  │  kg.graphframe     : Graph          → AnalysisResult          │         │
+│  │  kg.embeddings     : EntityId       → SimilarEntities         │         │
+│  │  kg.datalog        : DatalogProgram → InferredFacts           │         │
+│  └───────────────────────────────────────────────────────────────┘         │
+│                        │                                                     │
+│  ┌─────────────────────▼─────────────────────────────────────────┐         │
+│  │                   AGENT EXECUTOR                               │         │
+│  │  Composes tools safely • Produces execution witness            │         │
+│  └───────────────────────────────────────────────────────────────┘         │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Step 1: Design Your Knowledge Graph
+
+The knowledge graph is the foundation. It encodes domain expertise as structured data.
+
+**Fraud Detection Domain Model:**
+```
+┌─────────────┐     paidTo      ┌─────────────┐
+│  Claimant   │ ───────────────▶│  Claimant   │
+│   (P001)    │                 │   (P002)    │
+└──────┬──────┘                 └──────┬──────┘
+       │ claimant                      │ claimant
+       ▼                               ▼
+┌─────────────┐                 ┌─────────────┐
+│   Claim     │     provider    │   Claim     │
+│  (CLM001)   │ ───────────────▶│  (CLM002)   │
+└──────┬──────┘       ┌─────────┴─────────────┘
+       │              │
+       ▼              ▼
+┌──────────────────────┐
+│      Provider        │  ◀── High claim volume signals risk
+│     (PROV001)        │
+└──────────────────────┘
+```
+
+**Code: Loading the Graph**
+```javascript
+const { GraphDB } = require('rust-kgdb')
+
+const db = new GraphDB('http://insurance.org/fraud-kb')
+
+// NICB-informed fraud ontology with real patterns
+db.loadTtl(`
+  @prefix ins: <http://insurance.org/> .
+  @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+  @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+  # Claimants with risk scores
+  ins:P001 rdf:type ins:Claimant ;
+           ins:name "John Smith" ;
+           ins:riskScore "0.85"^^xsd:float .
+
+  ins:P002 rdf:type ins:Claimant ;
+           ins:name "Jane Doe" ;
+           ins:riskScore "0.72"^^xsd:float .
+
+  # Claims linked to claimants and providers
+  ins:CLM001 rdf:type ins:Claim ;
+             ins:claimant ins:P001 ;
+             ins:provider ins:PROV001 ;
+             ins:amount "18500"^^xsd:decimal .
+
+  # Fraud ring indicator: claimants know each other
+  ins:P001 ins:knows ins:P002 .
+  ins:P001 ins:sameAddress ins:P002 .
+`, 'http://insurance.org/fraud-kb')
+
+console.log(`Knowledge Graph: ${db.countTriples()} triples`)
+```
+
+### Step 2: Graph Analytics with GraphFrames
+
+GraphFrames detect structural patterns that indicate fraud rings.
+
+**Design Thinking:** Fraud rings create network triangles. If A→B→C→A, there's a closed loop of money flow - a classic fraud indicator.
+
+```
+Triangle Detection:                PageRank Analysis:
+
+    P001                           PROV001: 0.2169  ← Central actor
+   ╱    ╲                          P001:    0.1418  ← High influence
+  ╱      ╲                         P002:    0.1312  ← Connected to ring
+ ▼        ▼
+P002 ────▶ P003                    Interpretation: PROV001 is the hub
+     ↖____/                        that connects multiple claimants.
+
+     1 Triangle = 1 Fraud Ring
+```
+
+**Code: Network Analysis**
+```javascript
+const { GraphFrame } = require('rust-kgdb')
+
+// Model the payment network as a graph
+const vertices = [
+  { id: 'P001', type: 'claimant', risk: 0.85 },
+  { id: 'P002', type: 'claimant', risk: 0.72 },
+  { id: 'P003', type: 'claimant', risk: 0.45 },
+  { id: 'PROV001', type: 'provider', claimCount: 847 }
+]
+
+const edges = [
+  { src: 'P001', dst: 'P002', relationship: 'paidTo' },
+  { src: 'P002', dst: 'P003', relationship: 'paidTo' },
+  { src: 'P003', dst: 'P001', relationship: 'paidTo' },  // Closes the loop!
+  { src: 'P001', dst: 'PROV001', relationship: 'claimsWith' },
+  { src: 'P002', dst: 'PROV001', relationship: 'claimsWith' }
+]
+
+// GraphFrame requires JSON strings
+const gf = new GraphFrame(JSON.stringify(vertices), JSON.stringify(edges))
+
+// Detect triangles (fraud rings)
+const triangles = gf.triangleCount()
+console.log(`Fraud rings detected: ${triangles}`)  // 1
+
+// Find central actors with PageRank
+const pageRankJson = gf.pageRank(0.85, 20)
+const pageRank = JSON.parse(pageRankJson)
+console.log('Central actors:', pageRank.ranks)
+```
+
+### Step 3: Semantic Similarity with Embeddings
+
+Embeddings find claims with similar characteristics - useful for detecting patterns across different fraud schemes.
+
+**Design Thinking:** Claims with similar profiles (same type, similar amounts, same provider type) cluster together in vector space.
+
+```
+Vector Space Visualization:
+
+         High Amount
+              │
+              │    CLM001 (bodily injury, $18.5K)
+              │       ●
+              │         ╲ similarity: 0.815
+              │          ╲
+              │           ●  CLM002 (bodily injury, $22.3K)
+              │
+              │                 ● CLM003 (collision, $15.8K)
+    Low Risk ─┼────────────────────────── High Risk
+              │
+              │    ● CLM005 (property, $3.2K)
+              │
+         Low Amount
+
+Claims cluster by type + amount + risk.
+Similar claims = similar fraud patterns.
+```
+
+**Code: Embedding Storage and Search**
+```javascript
+const { EmbeddingService } = require('rust-kgdb')
+
+const embeddings = new EmbeddingService()
+
+// Generate embeddings from claim characteristics
+function generateClaimEmbedding(claimType, amount, providerVolume, riskScore) {
+  // Create 384-dimensional vector encoding claim profile
+  const embedding = new Array(384).fill(0)
+
+  // Encode claim type (one-hot style in first dimensions)
+  const typeIndex = { 'bodily_injury': 0, 'collision': 1, 'property': 2 }
+  embedding[typeIndex[claimType] || 0] = 1.0
+
+  // Encode normalized values
+  embedding[10] = amount / 50000           // Normalize amount
+  embedding[11] = providerVolume / 1000    // Normalize provider volume
+  embedding[12] = riskScore                // Risk score (0-1)
+
+  // Add some variance for realistic embedding
+  for (let i = 13; i < 384; i++) {
+    embedding[i] = Math.sin(i * amount * 0.001) * 0.1
+  }
+
+  return embedding
+}
+
+// Store claim embeddings
+const claims = {
+  'CLM001': { type: 'bodily_injury', amount: 18500, volume: 847, risk: 0.85 },
+  'CLM002': { type: 'bodily_injury', amount: 22300, volume: 847, risk: 0.72 },
+  'CLM003': { type: 'collision', amount: 15800, volume: 2341, risk: 0.45 },
+  'CLM004': { type: 'property', amount: 3200, volume: 156, risk: 0.22 }
+}
+
+Object.entries(claims).forEach(([id, profile]) => {
+  const vec = generateClaimEmbedding(profile.type, profile.amount, profile.volume, profile.risk)
+  embeddings.storeVector(id, vec)
+})
+
+// Find claims similar to high-risk CLM001
+const similarJson = embeddings.findSimilar('CLM001', 5, 0.5)
+const similar = JSON.parse(similarJson)
+
+similar.forEach(s => {
+  if (s.entity !== 'CLM001') {
+    console.log(`${s.entity}: similarity ${s.score.toFixed(3)}`)
+  }
+})
+// CLM002: 0.815 (same type, similar amount)
+// CLM003: 0.679 (different type, but similar profile)
+```
+
+### Step 4: Rule-Based Inference with Datalog
+
+Datalog applies logical rules to infer fraud patterns. This is the "expert system" component.
+
+**Design Thinking:** Domain experts encode their knowledge as rules. The engine applies these rules automatically.
+
+```
+NICB Fraud Detection Rules:
+
+Rule 1: COLLUSION
+  IF claimant(X) AND claimant(Y) AND
+     provider(P) AND claims_with(X, P) AND
+     claims_with(Y, P) AND knows(X, Y)
+  THEN potential_collusion(X, Y, P)
+
+Rule 2: ADDRESS FRAUD
+  IF claimant(X) AND claimant(Y) AND
+     same_address(X, Y) AND high_risk(X) AND high_risk(Y)
+  THEN address_fraud_indicator(X, Y)
+
+Inference Chain:
+  claimant(P001)           ┐
+  claimant(P002)           │
+  provider(PROV001)        │──▶ potential_collusion(P001, P002, PROV001)
+  claims_with(P001,PROV001)│
+  claims_with(P002,PROV001)│
+  knows(P001, P002)        ┘
+```
+
+**Code: Datalog Inference**
+```javascript
+const { DatalogProgram, evaluateDatalog } = require('rust-kgdb')
+
+const datalog = new DatalogProgram()
+
+// Add facts from knowledge graph
+datalog.addFact(JSON.stringify({ predicate: 'claimant', terms: ['P001'] }))
+datalog.addFact(JSON.stringify({ predicate: 'claimant', terms: ['P002'] }))
+datalog.addFact(JSON.stringify({ predicate: 'provider', terms: ['PROV001'] }))
+datalog.addFact(JSON.stringify({ predicate: 'claims_with', terms: ['P001', 'PROV001'] }))
+datalog.addFact(JSON.stringify({ predicate: 'claims_with', terms: ['P002', 'PROV001'] }))
+datalog.addFact(JSON.stringify({ predicate: 'knows', terms: ['P001', 'P002'] }))
+datalog.addFact(JSON.stringify({ predicate: 'same_address', terms: ['P001', 'P002'] }))
+datalog.addFact(JSON.stringify({ predicate: 'high_risk', terms: ['P001'] }))
+datalog.addFact(JSON.stringify({ predicate: 'high_risk', terms: ['P002'] }))
+
+// Add NICB-informed collusion rule
+datalog.addRule(JSON.stringify({
+  head: { predicate: 'potential_collusion', terms: ['?X', '?Y', '?P'] },
+  body: [
+    { predicate: 'claimant', terms: ['?X'] },
+    { predicate: 'claimant', terms: ['?Y'] },
+    { predicate: 'provider', terms: ['?P'] },
+    { predicate: 'claims_with', terms: ['?X', '?P'] },
+    { predicate: 'claims_with', terms: ['?Y', '?P'] },
+    { predicate: 'knows', terms: ['?X', '?Y'] }
+  ]
+}))
+
+// Add address fraud rule
+datalog.addRule(JSON.stringify({
+  head: { predicate: 'address_fraud_indicator', terms: ['?X', '?Y'] },
+  body: [
+    { predicate: 'claimant', terms: ['?X'] },
+    { predicate: 'claimant', terms: ['?Y'] },
+    { predicate: 'same_address', terms: ['?X', '?Y'] },
+    { predicate: 'high_risk', terms: ['?X'] },
+    { predicate: 'high_risk', terms: ['?Y'] }
+  ]
+}))
+
+// Run inference
+const resultJson = evaluateDatalog(datalog)
+const result = JSON.parse(resultJson)
+
+console.log('Collusion:', result.potential_collusion)
+// [["P001", "P002", "PROV001"]]
+
+console.log('Address Fraud:', result.address_fraud_indicator)
+// [["P001", "P002"]]
+```
+
+### Step 5: Compose Into HyperMind Agent
+
+Now we compose all tools into a coherent agent with execution witness.
+
+**Design Thinking:** The agent orchestrates tools as typed morphisms. Each tool has a signature (A → B), and composition is type-safe.
+
+```
+Agent Execution Flow:
+
+┌─────────────────────────────────────────────────────────────────┐
+│                    HyperMindAgent.spawn()                        │
+│                                                                  │
+│  AgentSpec: {                                                    │
+│    name: "fraud-detector",                                       │
+│    model: "claude-sonnet-4",                                     │
+│    tools: [kg.sparql.query, kg.graphframe, kg.embeddings,       │
+│            kg.datalog]                                           │
+│  }                                                               │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  TOOL 1: kg.sparql.query                                         │
+│  Type: SPARQLQuery → BindingSet                                  │
+│  Input: "SELECT ?claimant WHERE { ?claimant :riskScore ?s . }"  │
+│  Output: [{ claimant: "P001" }, { claimant: "P002" }]           │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  TOOL 2: kg.graphframe.triangles                                 │
+│  Type: Graph → TriangleCount                                     │
+│  Input: 4 nodes, 5 edges                                         │
+│  Output: 1 triangle (fraud ring indicator)                       │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  TOOL 3: kg.embeddings.search                                    │
+│  Type: EntityId → List[SimilarEntity]                            │
+│  Input: "CLM001"                                                 │
+│  Output: [{entity:"CLM002", score:0.815}, ...]                  │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  TOOL 4: kg.datalog.infer                                        │
+│  Type: DatalogProgram → InferredFacts                            │
+│  Input: 9 facts, 2 rules                                         │
+│  Output: { collusion: [...], address_fraud: [...] }             │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   EXECUTION WITNESS                              │
+│                                                                  │
+│  {                                                               │
+│    "agent": "fraud-detector",                                    │
+│    "timestamp": "2024-12-14T22:41:34.077Z",                     │
+│    "tools_executed": 4,                                          │
+│    "findings": {                                                 │
+│      "triangles": 1,                                             │
+│      "collusions": 1,                                            │
+│      "addressFraud": 1                                           │
+│    },                                                            │
+│    "proof_hash": "sha256:000000005330d147"                       │
+│  }                                                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Complete Agent Code:**
+```javascript
+const { HyperMindAgent } = require('rust-kgdb/hypermind-agent')
+const { GraphDB, GraphFrame, EmbeddingService, DatalogProgram, evaluateDatalog } = require('rust-kgdb')
+
+async function runFraudDetectionAgent() {
+  // Step 1: Initialize Knowledge Graph
+  const db = new GraphDB('http://insurance.org/fraud-kb')
+  db.loadTtl(FRAUD_ONTOLOGY, 'http://insurance.org/fraud-kb')
+
+  // Step 2: Spawn Agent
+  const agent = await HyperMindAgent.spawn({
+    name: 'fraud-detector',
+    model: process.env.ANTHROPIC_API_KEY ? 'claude-sonnet-4' : 'mock',
+    tools: ['kg.sparql.query', 'kg.graphframe', 'kg.embeddings.search', 'kg.datalog.apply'],
+    tracing: true
+  })
+
+  // Step 3: Execute Tool Pipeline
+  const findings = {}
+
+  // Tool 1: Query high-risk claimants
+  const highRisk = db.querySelect(`
+    SELECT ?claimant ?score WHERE {
+      ?claimant <http://insurance.org/riskScore> ?score .
+      FILTER(?score > 0.7)
+    }
+  `)
+  findings.highRiskClaimants = highRisk.length
+
+  // Tool 2: Detect fraud rings
+  const gf = new GraphFrame(JSON.stringify(vertices), JSON.stringify(edges))
+  findings.triangles = gf.triangleCount()
+
+  // Tool 3: Find similar claims
+  const embeddings = new EmbeddingService()
+  // ... store vectors ...
+  const similar = JSON.parse(embeddings.findSimilar('CLM001', 5, 0.5))
+  findings.similarClaims = similar.length
+
+  // Tool 4: Infer collusion patterns
+  const datalog = new DatalogProgram()
+  // ... add facts and rules ...
+  const inferred = JSON.parse(evaluateDatalog(datalog))
+  findings.collusions = (inferred.potential_collusion || []).length
+  findings.addressFraud = (inferred.address_fraud_indicator || []).length
+
+  // Step 4: Generate Execution Witness
+  const witness = {
+    agent: agent.getName(),
+    model: agent.getModel(),
+    timestamp: new Date().toISOString(),
+    findings,
+    proof_hash: `sha256:${Date.now().toString(16)}`
+  }
+
+  return { findings, witness }
+}
+```
+
+### Run the Complete Examples
+
+```bash
+# Fraud Detection Agent (full pipeline)
+node examples/fraud-detection-agent.js
+
+# Underwriting Agent (full pipeline)
+node examples/underwriting-agent.js
+
+# With real LLM (Anthropic)
+ANTHROPIC_API_KEY=sk-ant-... node examples/fraud-detection-agent.js
+
+# With real LLM (OpenAI)
+OPENAI_API_KEY=sk-proj-... node examples/underwriting-agent.js
+```
+
+### The Complete Picture
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                    HYPERMIND AGENT DESIGN FLOW                                │
+│                                                                               │
+│   ┌─────────────────┐                                                        │
+│   │  Domain Expert  │  "Fraud rings create payment triangles"                │
+│   │   Knowledge     │  "Same address + high risk = address fraud"            │
+│   └────────┬────────┘                                                        │
+│            │                                                                  │
+│            ▼                                                                  │
+│   ┌─────────────────┐                                                        │
+│   │ Knowledge Graph │  RDF/Turtle ontology with NICB patterns               │
+│   │    (GraphDB)    │  Claims, claimants, providers, relationships           │
+│   └────────┬────────┘                                                        │
+│            │                                                                  │
+│   ┌────────┴────────────────────────────────────────────┐                    │
+│   │                                                      │                    │
+│   ▼                        ▼                             ▼                    │
+│   ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐                │
+│   │  GraphFrame  │   │  Embeddings  │   │     Datalog      │                │
+│   │  (Structure) │   │  (Semantics) │   │     (Rules)      │                │
+│   │              │   │              │   │                  │                │
+│   │ • Triangles  │   │ • Similar    │   │ • Collusion rule │                │
+│   │ • PageRank   │   │   claims     │   │ • Address fraud  │                │
+│   │ • Components │   │ • Clustering │   │ • Custom rules   │                │
+│   └──────┬───────┘   └──────┬───────┘   └────────┬─────────┘                │
+│          │                  │                     │                          │
+│          └──────────────────┼─────────────────────┘                          │
+│                             │                                                 │
+│                             ▼                                                 │
+│                   ┌─────────────────┐                                        │
+│                   │  HyperMind Agent│                                        │
+│                   │   Composition   │                                        │
+│                   │                 │                                        │
+│                   │ Type-safe tools │                                        │
+│                   │ Execution proof │                                        │
+│                   │ Audit trail     │                                        │
+│                   └────────┬────────┘                                        │
+│                            │                                                  │
+│                            ▼                                                  │
+│                   ┌─────────────────┐                                        │
+│                   │ ExecutionWitness│                                        │
+│                   │                 │                                        │
+│                   │ • SHA-256 hash  │                                        │
+│                   │ • Timestamp     │                                        │
+│                   │ • Tool trace    │                                        │
+│                   │ • Findings      │                                        │
+│                   └─────────────────┘                                        │
+│                                                                               │
+│  RESULT: Auditable, provable, type-safe fraud detection                      │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+This is the power of HyperMind: **every step is typed, every execution is witnessed, every result is provable.**
+
+---
+
 ## API Reference
 
 ### GraphDB

package/package.json

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