rust-kgdb

AI Answers You Can Trust

The Problem: LLMs hallucinate. They make up facts, invent data, and confidently state falsehoods. In regulated industries (finance, healthcare, legal), this is not just annoying—it's a liability.

The Solution: HyperMind grounds every AI answer in YOUR actual data. Every response includes a complete audit trail. Same question = Same answer = Same proof.

Results

Models tested: Claude Sonnet 4 (90.9%), GPT-4o (81.8%)

Full Benchmark Report →

The Difference: Before & After

Before: Vanilla LLM (Unreliable)

// Ask LLM to query your database
const answer = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Find suspicious providers in my database' }]
});

console.log(answer.choices[0].message.content);
// "Based on my analysis, Provider P001 appears suspicious because..."
//
// PROBLEMS:
// ❌ Did it actually query your database? No - it's guessing
// ❌ Where's the evidence? None - it made up "Provider P001"
// ❌ Will this answer be the same tomorrow? No - probabilistic
// ❌ Can you audit this for regulators? No - black box

After: HyperMind (Verifiable)

// Ask HyperMind to query your database
const { HyperMindAgent, GraphDB } = require('rust-kgdb');

const db = new GraphDB('http://insurance.org/');
db.loadTtl(yourActualData, null);  // Your real data

const agent = new HyperMindAgent({ kg: db, model: 'gpt-4o' });
const result = await agent.call('Find suspicious providers');

console.log(result.answer);
// "Provider PROV001 has risk score 0.87 with 47 claims over $50,000"
//
// VERIFIED:
// ✅ Queried your actual database (SPARQL executed)
// ✅ Evidence included (47 real claims found)
// ✅ Reproducible (same hash every time)
// ✅ Full audit trail for regulators

console.log(result.reasoningTrace);
// [
//   { tool: 'kg.sparql.query', input: 'SELECT ?p WHERE...', output: '[PROV001]' },
//   { tool: 'kg.datalog.apply', input: 'highRisk(?p) :- ...', output: 'MATCHED' }
// ]

console.log(result.hash);
// "sha256:8f3a2b1c..." - Same question = Same answer = Same hash

The key insight: The LLM plans WHAT to look for. The database finds EXACTLY that. Every answer traces back to your actual data.

Quick Start

Installation

npm install rust-kgdb

Platforms: macOS (Intel/Apple Silicon), Linux (x64/ARM64), Windows (x64)

Basic Usage (5 Lines)

const { GraphDB } = require('rust-kgdb')

const db = new GraphDB('http://example.org/')
db.loadTtl(':alice :knows :bob .', null)
const results = db.querySelect('SELECT ?who WHERE { ?who :knows :bob }')
console.log(results)  // [{ bindings: { who: 'http://example.org/alice' } }]

Complete Example with AI Agent

const { GraphDB, HyperMindAgent, createSchemaAwareGraphDB } = require('rust-kgdb')

// Load your data
const db = createSchemaAwareGraphDB('http://insurance.org/')
db.loadTtl(`
  @prefix : <http://insurance.org/> .
  :CLM001 a :Claim ; :amount "50000" ; :provider :PROV001 .
  :PROV001 a :Provider ; :riskScore "0.87" ; :name "MedCorp" .
`, null)

// Create AI agent
const agent = new HyperMindAgent({
  kg: db,
  model: 'gpt-4o',
  apiKey: process.env.OPENAI_API_KEY
})

// Ask questions in plain English
const result = await agent.call('Find high-risk providers')

// Every answer includes:
// - The SPARQL query that was generated
// - The data that was retrieved
// - A reasoning trace showing how the conclusion was reached
// - A cryptographic hash for reproducibility
console.log(result.answer)
console.log(result.reasoningTrace)  // Full audit trail

Use Cases

Fraud Detection

const agent = new HyperMindAgent({
  kg: insuranceDB,
  name: 'fraud-detector',
  model: 'claude-3-opus'
})

const result = await agent.call('Find providers with suspicious billing patterns')
// Returns: List of providers with complete evidence trail
// - SPARQL queries executed
// - Rules that matched
// - Similar entities found via embeddings

Regulatory Compliance

const agent = new HyperMindAgent({
  kg: complianceDB,
  scope: { allowedGraphs: ['http://compliance.org/'] }  // Restrict access
})

const result = await agent.call('Check GDPR compliance for customer data flows')
// Returns: Compliance status with verifiable reasoning chain

Risk Assessment

const result = await agent.call('Calculate risk score for entity P001')
// Returns: Risk score with complete derivation
// - Which data points were used
// - Which rules were applied
// - Confidence intervals

Features

Core Database (SPARQL 1.1)

Rule-Based Reasoning (Datalog)

Graph Analytics (GraphFrames)

Vector Similarity (Embeddings)

AI Agent Framework (HyperMind)

Available Tools

Performance

How It Works

The Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              YOUR QUESTION                                   │
│                    "Find suspicious providers"                               │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  STEP 1: SCHEMA INJECTION                                                    │
│                                                                              │
│  LLM receives your question PLUS your actual data schema:                   │
│  • Classes: Claim, Provider, Policy (from YOUR database)                    │
│  • Properties: amount, riskScore, claimCount (from YOUR database)           │
│                                                                              │
│  The LLM can ONLY reference things that actually exist in your data.        │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  STEP 2: TYPED EXECUTION PLAN                                                │
│                                                                              │
│  LLM generates a plan using typed tools:                                    │
│  1. kg.sparql.query("SELECT ?p WHERE { ?p :riskScore ?r . FILTER(?r > 0.8)}")│
│  2. kg.datalog.apply("suspicious(?p) :- highRisk(?p), highClaimCount(?p)")  │
│                                                                              │
│  Each tool has defined inputs/outputs. Invalid combinations rejected.        │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  STEP 3: DATABASE EXECUTION                                                  │
│                                                                              │
│  The database executes the plan against YOUR ACTUAL DATA:                   │
│  • SPARQL query runs → finds 3 providers with riskScore > 0.8               │
│  • Datalog rules run → 1 provider matches "suspicious" pattern              │
│                                                                              │
│  Every step is recorded in the reasoning trace.                             │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  STEP 4: VERIFIED ANSWER                                                     │
│                                                                              │
│  Answer: "Provider PROV001 is suspicious (riskScore: 0.87, claims: 47)"     │
│                                                                              │
│  + Reasoning Trace: Every query, every rule, every result                   │
│  + Hash: sha256:8f3a2b1c... (reproducible)                                  │
│                                                                              │
│  Run the same question tomorrow → Same answer → Same hash                   │
└─────────────────────────────────────────────────────────────────────────────┘

Why Hallucination Is Impossible

The key insight: The LLM is a planner, not an oracle. It decides WHAT to look for. The database finds EXACTLY that. The answer is the intersection of LLM intelligence and database truth.

API Reference

GraphDB

class GraphDB {
  constructor(appGraphUri: string)
  loadTtl(ttlContent: string, graphName: string | null): void
  querySelect(sparql: string): QueryResult[]
  query(sparql: string): TripleResult[]
  countTriples(): number
  clear(): void
}

HyperMindAgent

class HyperMindAgent {
  constructor(options: {
    kg: GraphDB,           // Your knowledge graph
    model?: string,        // 'gpt-4o' | 'claude-3-opus' | etc.
    apiKey?: string,       // LLM API key
    memory?: MemoryManager,
    scope?: AgentScope,
    embeddings?: EmbeddingService
  })

  call(prompt: string): Promise<AgentResponse>
}

interface AgentResponse {
  answer: string
  reasoningTrace: ReasoningStep[]  // Audit trail
  hash: string                      // Reproducibility hash
}

GraphFrame

class GraphFrame {
  constructor(verticesJson: string, edgesJson: string)
  pageRank(resetProb: number, maxIter: number): string
  connectedComponents(): string
  shortestPaths(landmarks: string[]): string
  triangleCount(): number
  find(pattern: string): string  // Motif pattern matching
}

EmbeddingService

class EmbeddingService {
  storeVector(entityId: string, vector: number[]): void
  findSimilar(entityId: string, k: number, threshold: number): string
  rebuildIndex(): void
}

DatalogProgram

class DatalogProgram {
  addFact(factJson: string): void
  addRule(ruleJson: string): void
}

function evaluateDatalog(program: DatalogProgram): string
function queryDatalog(program: DatalogProgram, query: string): string

More Examples

Knowledge Graph

const { GraphDB } = require('rust-kgdb')

const db = new GraphDB('http://example.org/')
db.loadTtl(`
  @prefix : <http://example.org/> .
  :alice :knows :bob .
  :bob :knows :charlie .
  :charlie :knows :alice .
`, null)

console.log(`Loaded ${db.countTriples()} triples`)  // 3

const results = db.querySelect(`
  PREFIX : <http://example.org/>
  SELECT ?person WHERE { ?person :knows :bob }
`)
console.log(results)  // [{ bindings: { person: 'http://example.org/alice' } }]

Graph Analytics

const { GraphFrame } = require('rust-kgdb')

const graph = new GraphFrame(
  JSON.stringify([{id:'alice'}, {id:'bob'}, {id:'charlie'}]),
  JSON.stringify([
    {src:'alice', dst:'bob'},
    {src:'bob', dst:'charlie'},
    {src:'charlie', dst:'alice'}
  ])
)

console.log('Triangles:', graph.triangleCount())  // 1
console.log('PageRank:', JSON.parse(graph.pageRank(0.15, 20)))
console.log('Components:', JSON.parse(graph.connectedComponents()))

Rule-Based Reasoning

const { DatalogProgram, evaluateDatalog } = require('rust-kgdb')

const program = new DatalogProgram()
program.addFact(JSON.stringify({predicate: 'parent', terms: ['alice', 'bob']}))
program.addFact(JSON.stringify({predicate: 'parent', terms: ['bob', 'charlie']}))

// grandparent(X, Z) :- parent(X, Y), parent(Y, Z)
program.addRule(JSON.stringify({
  head: {predicate: 'grandparent', terms: ['?X', '?Z']},
  body: [
    {predicate: 'parent', terms: ['?X', '?Y']},
    {predicate: 'parent', terms: ['?Y', '?Z']}
  ]
}))

console.log('Inferred:', JSON.parse(evaluateDatalog(program)))
// grandparent(alice, charlie)

Semantic Similarity

const { EmbeddingService } = require('rust-kgdb')

const embeddings = new EmbeddingService()

// Store 384-dimension vectors
embeddings.storeVector('claim_001', new Array(384).fill(0.5))
embeddings.storeVector('claim_002', new Array(384).fill(0.6))
embeddings.rebuildIndex()

// HNSW similarity search
const similar = JSON.parse(embeddings.findSimilar('claim_001', 5, 0.7))
console.log('Similar:', similar)

Benchmarks

Performance (Measured)

Industry Comparison

AI Agent Accuracy

W3C Standards Compliance

Running Tests

npm test           # 42 feature tests
npm run test:jest  # 217 unit tests

Links

• npm: rust-kgdb
• GitHub: gonnect-uk/rust-kgdb
• Benchmark Report: HYPERMIND_BENCHMARK_REPORT.md
• Changelog: CHANGELOG.md

Advanced Topics

For those interested in the technical foundations of why HyperMind achieves deterministic AI reasoning.

Why It Works: The Technical Foundation

HyperMind's reliability comes from three mathematical foundations:

The Reasoning Trace (Audit Trail)

Every HyperMind answer includes a cryptographically-signed derivation showing exactly how the conclusion was reached:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           REASONING TRACE                                    │
│                                                                              │
│                    ┌────────────────────────────────┐                       │
│                    │      CONCLUSION (Root)         │                       │
│                    │  "Provider P001 is suspicious" │                       │
│                    │  Confidence: 94%               │                       │
│                    └───────────────┬────────────────┘                       │
│                                    │                                        │
│                    ┌───────────────┼───────────────┐                       │
│                    │               │               │                       │
│                    ▼               ▼               ▼                       │
│      ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐       │
│      │  Database Query  │ │ Rule Application │ │ Similarity Match │       │
│      │                  │ │                  │ │                  │       │
│      │ Tool: SPARQL     │ │ Tool: Datalog    │ │ Tool: Embeddings │       │
│      │ Result: 47 claims│ │ Result: MATCHED  │ │ Result: 87%      │       │
│      │ Time: 2.3ms      │ │ Rule: fraud(?P)  │ │ similar to known │       │
│      └──────────────────┘ └──────────────────┘ └──────────────────┘       │
│                                                                              │
│      HASH: sha256:8f3a2b1c4d5e...  (Reproducible, Auditable, Verifiable)   │
└─────────────────────────────────────────────────────────────────────────────┘

For Academics: Mathematical Foundations

HyperMind is built on rigorous mathematical foundations:

• Context Theory (Spivak's Ologs): Schema represented as a category where objects are classes and morphisms are properties
• Type Theory (Hindley-Milner): Every tool has a typed signature enabling compile-time validation
• Proof Theory (Curry-Howard): Proofs are programs, types are propositions - every conclusion has a derivation
• Category Theory: Tools as morphisms with validated composition

These foundations ensure that HyperMind transforms probabilistic LLM outputs into deterministic, verifiable reasoning chains.

Architecture Layers

┌─────────────────────────────────────────────────────────────────────────────┐
│                    INTELLIGENCE CONTROL PLANE                                │
│                                                                              │
│   ┌────────────────┐   ┌────────────────┐   ┌────────────────┐             │
│   │ Schema         │   │ Tool           │   │ Reasoning      │             │
│   │ Awareness      │   │ Validation     │   │ Trace          │             │
│   └───────┬────────┘   └───────┬────────┘   └───────┬────────┘             │
│           └────────────────────┼────────────────────┘                       │
│                                ▼                                            │
│   ┌─────────────────────────────────────────────────────────────────────┐  │
│   │                      HYPERMIND AGENT                                 │  │
│   │  User Query → LLM Planner → Typed Execution Plan → Tools → Answer   │  │
│   └─────────────────────────────────────────────────────────────────────┘  │
│                                ▼                                            │
│   ┌─────────────────────────────────────────────────────────────────────┐  │
│   │                      rust-kgdb ENGINE                                │  │
│   │  • GraphDB (SPARQL 1.1)    • GraphFrames (Analytics)                │  │
│   │  • Datalog (Rules)         • Embeddings (Similarity)                │  │
│   └─────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Security Model

HyperMind includes capability-based security:

const agent = new HyperMindAgent({
  kg: db,
  scope: new AgentScope({
    allowedGraphs: ['http://insurance.org/'],  // Restrict graph access
    allowedPredicates: ['amount', 'provider'], // Restrict predicates
    maxResultSize: 1000                        // Limit result size
  }),
  sandbox: {
    capabilities: ['ReadKG', 'ExecuteTool'],   // No WriteKG = read-only
    fuelLimit: 1_000_000                       // CPU budget
  }
})

Memory System

Agents have persistent memory across sessions:

const agent = new HyperMindAgent({
  kg: db,
  memory: new MemoryManager({
    workingMemorySize: 10,           // Current session cache
    episodicRetentionDays: 30,       // Episode history
    longTermGraph: 'http://memory/'  // Persistent knowledge
  })
})

License

Apache 2.0