rust-kgdb

"Any AI that cannot PROVE its conclusions is just sophisticated guessing."

BRAIN: Business Reasoning & AI Intelligence Network

What if your AI could show its work? Not just give you an answer, but prove exactly how it derived that answer—with cryptographic verification that auditors and regulators can independently validate?

Traditional LLM:                         BRAIN HyperMind Agent:
┌─────────────────────────────┐          ┌─────────────────────────────────────────┐
│ Input: "Is this fraudulent?"│          │ Input: "Is this fraudulent?"            │
│ Output: "Probability: 0.87" │          │ Output:                                 │
│         (No explanation)    │          │   FINDING: Circular payment fraud       │
│         (No proof)          │          │   PROOF: SHA-256 92be3c44...            │
│         (Hallucination risk)│          │   DATA: KGDB + Snowflake TPCH + BigQuery│
└─────────────────────────────┘          │   DERIVATION:                           │
                                         │     Step 1: cust001 -> cust002 ($711)   │
                                         │     Step 2: cust002 -> cust003 ($121)   │
                                         │     Step 3: cust003 -> cust001 ($7,498) │
                                         │     Step 4: [OWL:TRANSITIVE] Cycle!     │
                                         │   MEMORY: Matches Case #2847            │
                                         └─────────────────────────────────────────┘

Try it now:

npm install rust-kgdb
node node_modules/rust-kgdb/examples/fraud-underwriting-reallife-demo.js

The Problem We Solve

Your knowledge is scattered:

• Claims live in Snowflake TPCH_SF1
• Customer graph sits in Neo4j or KGDB
• Risk models run on BigQuery
• Compliance docs are in SharePoint

And your AI? It hallucinates because it can't see the full picture.

rust-kgdb unifies everything:

• In-memory KGDB with 449ns lookups (5-11x faster than RDFox)
• HyperFederate: KGDB + Snowflake + BigQuery in single SPARQL query
• ThinkingReasoner: Deductive AI with proof-carrying outputs
• RPC Proxy: Works in-memory (npm) or K8s cluster—both certified

What's New in v0.8.7

What if every AI conclusion came with a mathematical proof?

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

// Load YOUR ontology - rules are auto-generated, not hardcoded
const reasoner = new ThinkingReasoner()
reasoner.loadOntology(`
  @prefix ins: <http://insurance.example.org/> .
  @prefix owl: <http://www.w3.org/2002/07/owl#> .

  # This single line auto-generates transitivity rules
  ins:transfers a owl:TransitiveProperty .
`)

// Record observations (ground truth from your data)
reasoner.observe("Alice transfers $10K to Bob", { subject: "alice", predicate: "transfers", object: "bob" })
reasoner.observe("Bob transfers $9.5K to Carol", { subject: "bob", predicate: "transfers", object: "carol" })
reasoner.observe("Carol transfers $9K to Alice", { subject: "carol", predicate: "transfers", object: "alice" })

// Run deduction - derives: alice transfers to carol (transitivity!)
const result = reasoner.deduce()
// result.derivedFacts: 3 new facts
// result.proofs: 3 cryptographic witnesses
// result.derivationChain: step-by-step reasoning trace

The key insight: The LLM proposes hypotheses. The ThinkingReasoner validates them against your ontology. Only facts with valid proofs become assertions. No hallucinations possible—every conclusion traces back through a derivation chain to ground truth observations.

Derivation Chain (like Claude's thinking, but verifiable):

  Step 1: [OBSERVATION] Alice transfers to Bob
  Step 2: [OBSERVATION] Bob transfers to Carol
  Step 3: [RULE: owl:TransitiveProperty] Alice transfers to Carol
          Premises: [Step 1, Step 2]
          Proof Hash: a3f8c2...
  Step 4: [OBSERVATION] Carol transfers to Alice
  Step 5: [RULE: circularPayment] Circular payment detected: Alice → Bob → Carol → Alice
          Premises: [Step 1, Step 2, Step 4]
          Confidence: 0.85

See ThinkingReasoner: Deductive AI for complete documentation.

HyperMind Agent + Deductive Reasoning: The Complete Picture

What happens when you combine natural language understanding with provable deduction?

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

// 1. Create in-memory KGDB with your domain ontology
const db = new GraphDB('http://insurance.example.org/')
db.loadTtl(`
  @prefix ins: <http://insurance.example.org/> .
  @prefix owl: <http://www.w3.org/2002/07/owl#> .

  ins:transfers a owl:TransitiveProperty .
  ins:relatedTo a owl:SymmetricProperty .
  ins:FraudulentClaim rdfs:subClassOf ins:Claim .
`)

// 2. Create ThinkingReasoner (auto-generates rules from ontology)
const reasoner = new ThinkingReasoner()
reasoner.loadOntology(db.getOntology())

// 3. Create HyperMind Agent with deductive reasoning
const agent = new HyperMindAgent({
  kg: db,
  reasoner: reasoner,                    // Deductive reasoning engine
  federate: new RpcFederationProxy({     // Cross-database federation
    endpoint: 'http://localhost:30180'
  }),
  thinkingGraph: {
    enabled: true,                       // Show derivation chain
    streaming: true                      // Real-time thinking updates
  }
})

// 4. Natural language query with federated data + deductive reasoning
const result = await agent.call(`
  Find circular payment patterns in claims from the last 30 days.
  Cross-reference with Snowflake customer data and BigQuery risk scores.
  Show me the proof chain for any fraud detected.
`)

// Result includes:
// - answer: Natural language summary
// - sparql: Generated SPARQL query
// - federatedSql: Cross-database SQL
// - thinkingGraph: Full derivation chain
// - proofs: Cryptographic witnesses for each conclusion

console.log('Answer:', result.answer)
console.log('Proofs:', result.proofs.length)

// Display thinking graph (like Claude's thinking, but verifiable)
for (const step of result.thinkingGraph.derivationChain) {
  console.log(`[${step.step}] ${step.rule}: ${step.conclusion}`)
  if (step.proofHash) {
    console.log(`    Proof: ${step.proofHash}`)
  }
}

Output:

Answer: Found 3 circular payment patterns indicating potential fraud.
        Alice → Bob → Carol → Alice ($28,500 total)
        Provider #4521 → Clinic #892 → Provider #4521 ($156,000)

Proofs: 6

[1] SPARQL-EXEC: Query customer transfers from KGDB (2.3ms)
[2] FEDERATION: Join with Snowflake accounts (890ms)
[3] FEDERATION: Join with BigQuery risk scores (340ms)
[4] OBSERVATION: Alice transfers $10K to Bob
[5] OBSERVATION: Bob transfers $9.5K to Carol
[6] OBSERVATION: Carol transfers $9K to Alice
[7] DATALOG-INFER: owl:TransitiveProperty → Alice transfers to Carol
    Premises: [4, 5]
[8] DATALOG-INFER: circularPayment(Alice, Bob, Carol)
    Premises: [4, 5, 6]
    Proof: a3f8c2e7...
    Confidence: 0.92

The key difference from other AI frameworks:

What's New in v0.7.0

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

// Query across KGDB + Snowflake + BigQuery in single SQL
const federation = new RpcFederationProxy({ endpoint: 'http://localhost:30180' })
const result = await federation.query(`
  SELECT kg.*, sf.C_NAME, bq.name_popularity
  FROM graph_search('SELECT ?person WHERE { ?person a :Customer }') kg
  JOIN snowflake.CUSTOMER sf ON kg.custKey = sf.C_CUSTKEY
  LEFT JOIN bigquery.usa_names bq ON sf.C_NAME = bq.name
`)

See HyperFederate: Cross-Database Federation for complete documentation.

What's New in v0.6.79

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

See Native Graph Embeddings for complete documentation and benchmarks.

The Problem With AI Today

Here's what actually happens in every enterprise AI project:

Your fraud analyst asks a simple question: "Show me high-risk customers with large account balances who've had claims in the past 6 months."

Sounds simple. It's not.

The customer data lives in Snowflake. The risk scores are computed in your knowledge graph. The claims history sits in BigQuery. The policy details are in a legacy Oracle database. And nobody can write a query that spans all four.

So the analyst does what everyone does:

1. Export customers from Snowflake to CSV
2. Run a separate risk query in the graph database
3. Pull claims from BigQuery into another spreadsheet
4. Spend 3 hours in Excel doing VLOOKUP joins
5. Present "findings" that are already 6 hours stale

This is the reality of enterprise data in 2025. Knowledge is scattered across dozens of systems. Every "simple" question requires a data engineering project. And when you finally get your answer, you can't trace how it was derived.

Now add AI to this mess.

Your analyst asks ChatGPT the same question. It responds confidently: "Customer #4521 is high-risk with $847,000 in account balance and 3 recent claims."

The analyst opens an investigation. Two weeks later, legal discovers Customer #4521 doesn't exist. The AI made up everything—the customer ID, the balance, the claims. The AI had no access to your data. It just generated plausible-sounding text.

This keeps happening:

• A lawyer cites "Smith v. Johnson (2019)" in court. That case doesn't exist.
• A doctor avoids prescribing "Nexapril" for cardiac patients. Nexapril isn't a real drug.
• A fraud analyst flags Account #7842 for money laundering. It belongs to a children's charity.

Every time, the same pattern: Data is scattered. AI can't see it. AI fabricates. People get hurt.

The Engineering Problem

The root cause is simple: LLMs are language models, not databases. They predict plausible text. They don't look up facts.

When you ask "Has Provider #4521 shown suspicious patterns?", the LLM doesn't query your claims database. It generates text that sounds like an answer based on patterns from its training data.

The industry's response? Add guardrails. Use RAG. Fine-tune models.

These help, but they're patches:

• RAG retrieves similar documents - similar isn't the same as correct
• Fine-tuning teaches patterns, not facts
• Guardrails catch obvious errors, but "Provider #4521 has billing anomalies" sounds perfectly plausible

A real solution requires a different architecture. One built on solid engineering principles, not hope.

The Solution: Query Generation, Not Answer Generation

What if we're thinking about AI wrong?

Every enterprise wants the same thing: ask a question in plain English, get an accurate answer from their data. But we've been trying to make the AI know the answer. That's backwards.

The AI doesn't need to know anything. It just needs to know how to ask.

Think about what's actually happening when a fraud analyst asks: "Show me high-risk customers with large balances."

The analyst already has everything needed to answer this question:

• Customer data in Snowflake
• Risk scores in the knowledge graph
• Account balances in the core banking system
• Complete audit logs of every transaction

The problem isn't missing data. It's that no human can write a query that spans all these systems. SQL doesn't work on graphs. SPARQL doesn't work on Snowflake. And nobody has 4 hours to manually join CSVs.

The breakthrough: What if AI generated the query instead of the answer?

The Old Way (Dangerous):
  Human: "Show me high-risk customers with large balances"
  AI: "Customer #4521 has $847K and high risk score"     <-- FABRICATED

The New Way (Verifiable):
  Human: "Show me high-risk customers with large balances"
  AI: Understands intent → Generates federated SQL:

      SELECT kg.customer, kg.risk_score, sf.balance
      FROM graph_search('...risk assessment...') kg
      JOIN snowflake.ACCOUNTS sf ON kg.customer_id = sf.id
      WHERE kg.risk_score > 0.8 AND sf.balance > 100000

  Database: Executes across KGDB + Snowflake + BigQuery
  Result: Real customers. Real balances. Real risk scores.
          With SHA-256 proof hash for audit trail.          <-- VERIFIABLE

The AI never touches your data. It translates human language into precise queries. The database executes against real systems. Every answer traces back to actual records.

rust-kgdb is not an AI that knows answers. It's an AI that knows how to ask the right questions—across every system where your knowledge lives.

The Business Value

For Enterprises:

• Zero hallucinations - Every answer traces back to your actual data
• Full audit trail - Regulators can verify every AI decision (SOX, GDPR, FDA 21 CFR Part 11)
• No infrastructure - Runs embedded in your app, no servers to manage
• Instant deployment - npm install and you're running

For Engineering Teams:

• 449ns lookups - 5-11x faster than RDFox (2.5-5µs), measured on commodity hardware
• 24 bytes per triple - 25% more memory efficient than competitors
• 132K writes/sec - Handle enterprise transaction volumes
• 94% recall on memory retrieval - Agent remembers past queries accurately

For AI/ML Teams:

• 85.7% SPARQL accuracy - vs 0% with vanilla LLMs (GPT-4o + HyperMind schema injection)
• 16ms similarity search - Find related entities across 10K vectors
• Recursive reasoning - Datalog rules cascade automatically (fraud rings, compliance chains)
• Schema-aware generation - AI uses YOUR ontology, not guessed class names

RDF2Vec Native Graph Embeddings:

• 98 ns embedding lookup - 500-1000x faster than external APIs (no HTTP latency)
• 44.8 µs similarity search - 22.3K operations/sec in-process
• Composite multi-vector - RRF fusion of RDF2Vec + OpenAI with -2% overhead at scale
• Automatic triggers - Vectors generated on graph upsert, no batch pipelines

The math matters. When your fraud detection runs 5-11x faster, you catch fraud before payments clear. When your agent remembers with 94% accuracy, analysts don't repeat work. When every decision has a proof hash, you pass audits.

Why rust-kgdb and HyperMind?

The question isn't "Can AI answer my question?" It's "Can I trust the answer?"

Every AI framework makes the same mistake: they treat the LLM as the source of truth. LangChain. LlamaIndex. AutoGPT. They all assume the model knows things. It doesn't. It generates plausible text. There's a difference.

We built rust-kgdb on a contrarian principle: Never trust the AI. Verify everything.

The LLM proposes a query. The type system validates it against your actual schema. The sandbox executes it in isolation. The database returns only facts that exist. The proof DAG creates a cryptographic audit trail.

At no point does the AI "know" anything. It's a translator—from human intent to precise queries—with four layers of verification before anything touches your data.

This is the difference between an AI that sounds right and an AI that is right.

The Engineering Foundation

The Architecture Difference

+===========================================================================+
|                                                                           |
|   TRADITIONAL AI ARCHITECTURE (Dangerous)                                 |
|                                                                           |
|   +-------------+     +-------------+     +-------------+                 |
|   |   Human     | --> |    LLM      | --> |  Database   |                 |
|   |   Request   |     |  (Trusted)  |     |   (Maybe)   |                 |
|   +-------------+     +-------------+     +-------------+                 |
|                             |                                             |
|                             v                                             |
|                       "Provider #4521                                     |
|                        has anomalies"                                     |
|                       (FABRICATED!)                                       |
|                                                                           |
|   Problem: LLM generates answers directly. No verification.               |
|                                                                           |
+===========================================================================+

+===========================================================================+
|                                                                           |
|   rust-kgdb + HYPERMIND ARCHITECTURE (Safe)                               |
|                                                                           |
|   +-------------+     +-------------+     +-------------+                 |
|   |   Human     | --> |  HyperMind  | --> | rust-kgdb   |                 |
|   |   Request   |     |   Agent     |     |  GraphDB    |                 |
|   +-------------+     +------+------+     +------+------+                 |
|                              |                   |                        |
|        +---------+-----------+-----------+-------+                        |
|        |         |           |           |                                |
|        v         v           v           v                                |
|   +--------+ +--------+ +--------+ +--------+                             |
|   | Type   | | WASM   | | Proof  | | Schema |                             |
|   | Theory | | Sandbox| | DAG    | | Cache  |                             |
|   +--------+ +--------+ +--------+ +--------+                             |
|   Hindley-  Capability  SHA-256    Your                                   |
|   Milner    Isolation   Audit      Ontology                               |
|                                                                           |
|   Result: "SELECT ?anomaly WHERE { :Provider4521 :hasAnomaly ?anomaly }"  |
|           Executes against YOUR data. Returns REAL facts.                 |
|                                                                           |
+===========================================================================+

+===========================================================================+
|                                                                           |
|   THE TRUST MODEL: Four Layers of Defense                                 |
|                                                                           |
|   Layer 1: AGENT (Untrusted)                                              |
|   +---------------------------------------------------------------------+ |
|   | LLM generates intent: "Find suspicious providers"                   | |
|   | - Can suggest queries                                               | |
|   | - Cannot execute anything directly                                  | |
|   | - All outputs are validated                                         | |
|   +---------------------------------------------------------------------+ |
|                              | validated intent                           |
|                              v                                            |
|   Layer 2: PROXY (Verified)                                               |
|   +---------------------------------------------------------------------+ |
|   | Type-checks against schema: Is "Provider" a valid class?            | |
|   | - Hindley-Milner type inference                                     | |
|   | - Schema validation (YOUR ontology)                                 | |
|   | - Rejects malformed queries before execution                        | |
|   +---------------------------------------------------------------------+ |
|                              | typed query                                |
|                              v                                            |
|   Layer 3: SANDBOX (Isolated)                                             |
|   +---------------------------------------------------------------------+ |
|   | WASM execution with capability-based security                       | |
|   | - Fuel metering (prevents infinite loops)                           | |
|   | - Memory isolation (no access to host)                              | |
|   | - Explicit capability grants (read-only, write, admin)              | |
|   +---------------------------------------------------------------------+ |
|                              | sandboxed execution                        |
|                              v                                            |
|   Layer 4: DATABASE (Authoritative)                                       |
|   +---------------------------------------------------------------------+ |
|   | rust-kgdb executes query against YOUR actual data                   | |
|   | - 449ns lookups (5-11x faster than RDFox)                           | |
|   | - Returns only facts that exist                                     | |
|   | - Generates SHA-256 proof hash for audit                            | |
|   +---------------------------------------------------------------------+ |
|                                                                           |
|   MATHEMATICAL FOUNDATIONS:                                               |
|   * Category Theory: Tools as morphisms (A -> B), composable             |
|   * Type Theory: Hindley-Milner ensures query well-formedness            |
|   * Proof Theory: Every execution produces a cryptographic witness       |
|                                                                           |
+===========================================================================+

The key insight: The LLM is creative but unreliable. The database is reliable but not creative. HyperMind bridges them with mathematical guarantees - the LLM proposes, the type system validates, the sandbox isolates, and the database executes. No hallucinations possible.

The Technical Problem (SPARQL Generation)

Beyond hallucination, there's a practical issue: LLMs can't write correct SPARQL.

We asked GPT-4 to write a simple SPARQL query: "Find all professors."

It returned this broken output:

    ```sparql
    SELECT ?professor WHERE { ?professor a ub:Faculty . }
    ```
    This query retrieves faculty members from the knowledge graph.

Three problems: (1) markdown code fences break the parser, (2) ub:Faculty doesn't exist in the schema (it's ub:Professor), and (3) the explanation text is mixed with the query. Result: Parser error. Zero results.

This isn't a cherry-picked failure. When we ran the standard LUBM benchmark (14 queries, 3,272 triples), vanilla LLMs produced valid, correct SPARQL 0% of the time.

We built rust-kgdb to fix this.

Architecture: What Powers rust-kgdb

+---------------------------------------------------------------------------------+
|                           YOUR APPLICATION                                       |
|                 (Fraud Detection, Underwriting, Compliance)                      |
+------------------------------------+--------------------------------------------+
                                     |
+------------------------------------v--------------------------------------------+
|                    HYPERMIND AGENT FRAMEWORK (SDK Layer)                         |
|  +----------------------------------------------------------------------------+ |
|  |  Mathematical Abstractions (High-Level)                                     | |
|  |  * TypeId: Hindley-Milner type system with refinement types                | |
|  |  * LLMPlanner: Natural language -> typed tool pipelines                     | |
|  |  * WasmSandbox: WASM isolation with capability-based security             | |
|  |  * AgentBuilder: Fluent composition of typed tools                         | |
|  |  * ExecutionWitness: Cryptographic proofs (SHA-256)                        | |
|  +----------------------------------------------------------------------------+ |
|                                     |                                            |
|                    Category Theory: Tools as Morphisms (A -> B)                   |
|                    Proof Theory: Every execution has a witness                   |
+------------------------------------+--------------------------------------------+
                                     | NAPI-RS Bindings
+------------------------------------v--------------------------------------------+
|                    RUST CORE ENGINE (Native Performance)                         |
|  +----------------------------------------------------------------------------+ |
|  |  GraphDB          | RDF/SPARQL quad store   | 449ns lookups, 24 bytes/triple |
|  |  GraphFrame       | Graph algorithms        | WCOJ optimal joins, PageRank  |
|  |  EmbeddingService | Vector similarity       | HNSW index, 1-hop ARCADE cache|
|  |  DatalogProgram   | Rule-based reasoning    | Semi-naive evaluation         |
|  |  Pregel           | BSP graph processing    | Iterative algorithms          |
|  +----------------------------------------------------------------------------+ |
|                                                                                  |
|  W3C Standards: SPARQL 1.1 (100%) | RDF 1.2 | OWL 2 RL | SHACL | RDFS          |
|  Storage Backends: InMemory | RocksDB | LMDB                                     |
|  Distribution: HDRF Partitioning | Raft Consensus | gRPC                         |
+----------------------------------------------------------------------------------+

Key Insight: The Rust core provides raw performance (449ns lookups). The HyperMind framework adds mathematical guarantees (type safety, composition laws, proof generation) without sacrificing speed.

What's Rust Core vs SDK Layer?

All major capabilities are implemented in Rust via the HyperMind SDK crates (hypermind-types, hypermind-runtime, hypermind-sdk). The JavaScript/TypeScript layer is a thin binding that exposes these Rust capabilities for Node.js applications.

Security Model: All interactions with Rust components flow through NAPI-RS bindings with memory isolation. The WasmSandbox wraps these bindings with capability-based access control, ensuring agents can only invoke tools they're explicitly granted. This provides defense-in-depth: NAPI-RS for memory safety, WasmSandbox for capability control.

The Solution

rust-kgdb is a knowledge graph database with a neuro-symbolic agent framework called HyperMind. Instead of hoping the LLM gets the syntax right, we use mathematical type theory to guarantee correctness.

The same query through HyperMind:

PREFIX ub: <http://swat.cse.lehigh.edu/onto/univ-bench.owl#>
SELECT ?professor WHERE { ?professor a ub:Professor . }

Result: 15 professors returned in 2.3ms.

The difference? HyperMind treats tools as typed morphisms (category theory), validates queries at compile-time (type theory), and produces cryptographic witnesses for every execution (proof theory). The LLM plans; the math executes.

Accuracy improvement: 0% -> 86.4% on the LUBM benchmark.

Native Graph Embeddings: RDF2Vec Engine

Traditional embedding pipelines introduce significant latency: serialize your entity, make an HTTP request to OpenAI or Cohere, wait 200-500ms, parse the response. For applications requiring real-time similarity—fraud detection, recommendation engines, entity resolution—this latency model becomes a critical bottleneck.

RDF2Vec takes a fundamentally different approach. Instead of treating entities as text to be embedded by external APIs, it learns vector representations directly from your graph's topology. The algorithm performs random walks across your knowledge graph, treating the resulting paths as "sentences" that capture structural relationships. These walks train a Word2Vec model in-process, producing embeddings that encode how entities relate to each other.

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

// Load your knowledge graph
const db = new GraphDB('http://enterprise/claims')
db.loadTtl(claimsOntology, null)  // 130,923 triples/sec throughput

// Initialize the RDF2Vec engine
const rdf2vec = new Rdf2VecEngine()

// Train embeddings from graph structure
// Walks capture: Provider → submits → Claim → involves → Patient
const walks = extractRandomWalks(db)
rdf2vec.train(JSON.stringify(walks))  // 1,207 walks/sec → 384-dim vectors

// Retrieve embeddings with microsecond latency
const embedding = rdf2vec.getEmbedding('http://claims/provider/4521')  // 68 µs

// Find structurally similar entities
const similar = rdf2vec.findSimilar(provider, candidateProviders, 10)  // 303 µs

Performance: Why Microseconds Matter

Practical Impact: When investigating a flagged claim, an analyst might check 50 similar providers. At 300ms per API call, that's 15 seconds of waiting. With RDF2Vec at 303µs per lookup, the same operation completes in 15 milliseconds—a 1,000x improvement that transforms the user experience from "waiting for AI" to "instant insight."

Multi-Vector Composite Embeddings with RRF

Real-world similarity often requires multiple perspectives. A claim's structural relationships (RDF2Vec) tell a different story than its textual description (OpenAI) or domain-specific features (custom model). The EmbeddingService supports composite embeddings with Reciprocal Rank Fusion (RRF) to combine these views:

const service = new EmbeddingService()

// Store embeddings from multiple sources
service.storeComposite('CLM-2024-0847', JSON.stringify({
  rdf2vec: rdf2vec.getEmbedding('CLM-2024-0847'),   // Graph structure
  openai: await openaiEmbed(claimNarrative),         // Semantic content
  domain: fraudRiskEmbedding                         // Domain-specific signals
}))

// RRF fusion combines rankings from each source
// Formula: Score = Σ(1 / (k + rank_i)), k=60
const similar = service.findSimilarComposite('CLM-2024-0847', 10, 0.7, 'rrf')

Distributed Cluster Benchmarks (Kubernetes)

For deployments exceeding single-node capacity, rust-kgdb supports distributed execution across Kubernetes clusters. Verified benchmarks on the LUBM academic dataset:

Configuration: 1 coordinator + 3 executors, HDRF partitioning, NodePort access at localhost:30080. Triples distribute automatically across executors; multi-hop joins execute seamlessly across partition boundaries.

End-to-End Pipeline Throughput

For detailed configuration options, see Walk Configuration and Auto-Embedding Triggers below.

The Deeper Problem: AI Agents Forget

Fixing SPARQL syntax is table stakes. Here's what keeps enterprise architects up at night:

Scenario: Your fraud detection agent correctly identified a circular payment ring last Tuesday. Today, an analyst asks: "Show me similar patterns to what we found last week."

The LLM response: "I don't have access to previous conversations. Can you describe what you're looking for?"

The agent forgot everything.

Every enterprise AI deployment hits the same wall:

• No Memory: Each session starts from zero - expensive recomputation, no learning
• No Context Window Management: Hit token limits? Lose critical history
• No Idempotent Responses: Same question, different answer - compliance nightmare
• No Provenance Chain: "Why did the agent flag this claim?" - silence

LangChain's solution: Vector databases. Store conversations, retrieve via similarity.

The problem: Similarity isn't memory. When your underwriter asks "What did we decide about claims from Provider X?", you need:

1. Temporal awareness - What we decided last month vs yesterday
2. Semantic edges - The decision relates to these specific claims
3. Epistemological stratification - Fact vs inference vs hypothesis
4. Proof chain - Why we decided this, not just that we did

This requires a Memory Hypergraph - not a vector store.

Memory Hypergraph: How AI Agents Remember

rust-kgdb introduces the Memory Hypergraph - a temporal knowledge graph where agent memory is stored in the same quad store as your domain knowledge, with hyper-edges connecting episodes to KG entities.

+---------------------------------------------------------------------------------+
|                         MEMORY HYPERGRAPH ARCHITECTURE                           |
|                                                                                  |
|   +-------------------------------------------------------------------------+   |
|   |                    AGENT MEMORY LAYER (am: graph)                        |   |
|   |                                                                          |   |
|   |   Episode:001                Episode:002                Episode:003      |   |
|   |   +---------------+         +---------------+         +---------------+ |   |
|   |   | Fraud ring    |         | Underwriting  |         | Follow-up     | |   |
|   |   | detected in   |         | denied claim  |         | investigation | |   |
|   |   | Provider P001 |         | from P001     |         | on P001       | |   |
|   |   |               |         |               |         |               | |   |
|   |   | Dec 10, 14:30 |         | Dec 12, 09:15 |         | Dec 15, 11:00 | |   |
|   |   | Score: 0.95   |         | Score: 0.87   |         | Score: 0.92   | |   |
|   |   +-------+-------+         +-------+-------+         +-------+-------+ |   |
|   |           |                         |                         |         |   |
|   +-----------+-------------------------+-------------------------+---------+   |
|               | HyperEdge:              | HyperEdge:              |             |
|               | "QueriedKG"             | "DeniedClaim"           |             |
|               v                         v                         v             |
|   +-------------------------------------------------------------------------+   |
|   |                    KNOWLEDGE GRAPH LAYER (domain graph)                  |   |
|   |                                                                          |   |
|   |      Provider:P001 --------------> Claim:C123 <---------- Claimant:C001 |   |
|   |           |                            |                        |        |   |
|   |           | :hasRiskScore              | :amount                | :name  |   |
|   |           v                            v                        v        |   |
|   |        "0.87"                       "50000"                 "John Doe"   |   |
|   |                                                                          |   |
|   |      +-------------------------------------------------------------+    |   |
|   |      |  SAME QUAD STORE - Single SPARQL query traverses BOTH       |    |   |
|   |      |  memory graph AND knowledge graph!                          |    |   |
|   |      +-------------------------------------------------------------+    |   |
|   |                                                                          |   |
|   +-------------------------------------------------------------------------+   |
|                                                                                  |
|   +-------------------------------------------------------------------------+   |
|   |                         TEMPORAL SCORING FORMULA                         |   |
|   |                                                                          |   |
|   |   Score = α × Recency + β × Relevance + γ × Importance                   |   |
|   |                                                                          |   |
|   |   where:                                                                 |   |
|   |     Recency    = 0.995^hours (12% decay/day)                            |   |
|   |     Relevance  = cosine_similarity(query, episode)                      |   |
|   |     Importance = log10(access_count + 1) / log10(max + 1)               |   |
|   |                                                                          |   |
|   |   Default: α=0.3, β=0.5, γ=0.2                                          |   |
|   +-------------------------------------------------------------------------+   |
|                                                                                  |
+---------------------------------------------------------------------------------+

Why This Matters for Enterprise AI

Without Memory Hypergraph (LangChain, LlamaIndex):

// Ask about last week's findings
agent.chat("What fraud patterns did we find with Provider P001?")
// Response: "I don't have that information. Could you describe what you're looking for?"
// Cost: Re-run entire fraud detection pipeline ($5 in API calls, 30 seconds)

With Memory Hypergraph (rust-kgdb HyperMind Framework):

// 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
})

// 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:

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 .
  }
  ?claim :provider ?provider ; :amount ?claimAmount .
  FILTER(?claimAmount > 25000)
}

You never write this - the typed API builds it for you.

Rolling Context Window

Token limits are real. rust-kgdb uses a rolling time window strategy to find the right context:

+---------------------------------------------------------------------------------+
|                         ROLLING CONTEXT WINDOW                                   |
|                                                                                  |
|   Query: "What did we find about Provider P001?"                                |
|                                                                                  |
|   Pass 1: Search last 1 hour      -> 0 episodes found -> expand                   |
|   Pass 2: Search last 24 hours    -> 1 episode found (not enough) -> expand       |
|   Pass 3: Search last 7 days      -> 3 episodes found -> within token budget ✓    |
|                                                                                  |
|   Context returned:                                                              |
|   +--------------------------------------------------------------------------+  |
|   |  Episode 003 (Dec 15): "Follow-up investigation on P001..."              |  |
|   |  Episode 002 (Dec 12): "Underwriting denied claim from P001..."          |  |
|   |  Episode 001 (Dec 10): "Fraud ring detected in Provider P001..."         |  |
|   |                                                                          |  |
|   |  Estimated tokens: 847 / 8192 max                                        |  |
|   |  Time window: 7 days                                                     |  |
|   |  Search passes: 3                                                        |  |
|   +--------------------------------------------------------------------------+  |
|                                                                                  |
+---------------------------------------------------------------------------------+

Idempotent Responses via Semantic Hashing

Same question = Same answer. Even with different wording. Critical for compliance.

// First call: Compute answer, cache with semantic hash
const result1 = await agent.call("Analyze claims from Provider P001")
// Semantic Hash: semhash:fraud-provider-p001-claims-analysis

// Second call (different wording, same intent): Cache HIT!
const result2 = await agent.call("Show me P001's claim patterns")
// Cache HIT - same semantic hash: semhash:fraud-provider-p001-claims-analysis

// Third call (exact same): Also cache hit
const result3 = await agent.call("Analyze claims from Provider P001")
// Cache HIT - same semantic hash: semhash:fraud-provider-p001-claims-analysis

// Compliance officer: "Why are these identical?"
// You: "Semantic hashing - same meaning, same output, regardless of phrasing."

How it works: Query embeddings are hashed via Locality-Sensitive Hashing (LSH) with random hyperplane projections. Semantically similar queries map to the same bucket.

Research Foundation:

• SimHash (Charikar, 2002) - Random hyperplane projections for cosine similarity
• Semantic Hashing (Salakhutdinov & Hinton, 2009) - Deep autoencoders for binary codes
• Learning to Hash (Wang et al., 2018) - Survey of neural hashing methods

Implementation: 384-dim embeddings -> LSH with 64 hyperplanes -> 64-bit semantic hash

Benefits:

• Semantic deduplication - "Find fraud" and "Detect fraudulent activity" hit same cache
• Cost reduction - Avoid redundant LLM calls for paraphrased questions
• Consistency - Same answer for same intent, audit-ready
• Sub-linear lookup - O(1) hash lookup vs O(n) embedding comparison

What This Is

World's first mobile-native knowledge graph database with clustered distribution and mathematically-grounded HyperMind agent framework.

Most graph databases were designed for servers. Most AI agents are built on prompt engineering and hope. We built both from the ground up - the database for performance, the agent framework for correctness:

1. Mobile-First: Runs natively on iOS and Android with zero-copy FFI
2. Standalone + Clustered: Same codebase scales from smartphone to Kubernetes
3. Open Standards: W3C SPARQL 1.1, RDF 1.2, OWL 2 RL, SHACL - no vendor lock-in
4. Mathematical Foundations: Type theory, category theory, proof theory - not prompt engineering
5. Worst-Case Optimal Joins: WCOJ algorithm guarantees O(N^(ρ/2)) complexity

Published Benchmarks

We don't make claims we can't prove. All measurements use publicly available, peer-reviewed benchmarks.

Public Benchmarks Used:

• LUBM (Lehigh University Benchmark) - Standard RDF/SPARQL benchmark since 2005
• SP2Bench - DBLP-based SPARQL performance benchmark
• W3C SPARQL 1.1 Conformance Suite - Official W3C test cases

Comparison Baselines:

• RDFox - Oxford Semantic Technologies' commercial RDF database (industry gold standard)
• Apache Jena - Apache Foundation's open-source RDF framework
• Tentris - Tensor-based RDF store from DICE Research (University of Paderborn)
• AllegroGraph - Franz Inc's commercial graph database with AI features

Honest Feature Comparison

Where Others Win:

• RDFox: More mature OWL reasoning, better incremental maintenance, proven at billion-triple scale
• Tentris: Tensor algebra enables certain complex joins faster than traditional indexing
• AllegroGraph: Longer track record (25+ years), extensive enterprise integrations, Prolog-like queries
• Jena: Largest ecosystem, most tutorials, best community support

Where rust-kgdb Wins:

• Raw Speed: 5-11x faster lookups than RDFox due to zero-copy Rust architecture
• Mobile: Only RDF database with native iOS/Android FFI bindings
• AI Integration: HyperMind is the only type-safe agent framework with schema-aware SPARQL generation
• Embeddings: Native HNSW vector search integrated with symbolic reasoning
• Price: Enterprise features at open-source pricing

How We Measured

• Dataset: LUBM benchmark (industry standard since 2005)
  • LUBM(1): 3,272 triples, 30 classes, 23 properties
  • LUBM(10): ~32K triples for bulk insert testing
• Hardware: MacBook Pro 16,1 (2019) - Intel Core i9-9980HK @ 2.40GHz, 8 cores/16 threads, 64GB DDR4
  • Note: This is commodity developer hardware. Production servers will see improved numbers.
• Methodology: 10,000+ iterations, cold-start, statistical analysis via Criterion.rs
• Comparison: Apache Jena 4.x, RDFox 7.x under identical conditions

Baseline Sources:

• RDFox: Oxford Semantic Technologies documentation - 2.5-5µs lookups, 32 bytes/triple
• Tentris: ISWC 2020 paper - Tensor-based execution
• AllegroGraph: Franz Inc benchmarks - Enterprise scale focus
• Apache Jena: TDB2 documentation - Industry-standard baseline

WCOJ (Worst-Case Optimal Join) Comparison

WCOJ is the gold standard for multi-way join performance. We implement it; here's how we compare:

Research Foundation:

• Leapfrog Triejoin (Veldhuizen 2014) - Original WCOJ algorithm
• Tentris WCOJ Update (DICE 2025) - Latest tensor-based improvements
• AGM Bound (Atserias et al. 2008) - Theoretical optimality proof

Why WCOJ Matters:

Traditional joins: O(N^k) where k = number of relations WCOJ joins: O(N^(rho/2)) where rho = fractional edge cover (always <= k)

For a 5-way join on 1M triples:

• Traditional: Up to 10^30 intermediate results (impractical)
• WCOJ: Bounded by actual output size (practical)

Example: Triangle Query (3-way self-join)
  Traditional Join: O(N^3) = 10^18 for 1M triples
  WCOJ: O(N^1.5) = 10^9 for 1M triples (1 billion x faster worst-case)

Try it yourself:

node hypermind-benchmark.js  # Compare HyperMind vs Vanilla LLM accuracy
cargo bench --package storage --bench triple_store_benchmark  # Run Rust benchmarks

Why Embeddings? The Rise of Neuro-Symbolic AI

The Problem with Pure Symbolic Systems

Traditional knowledge graphs are powerful for structured reasoning:

SELECT ?fraud WHERE {
  ?claim :amount ?amt .
  FILTER(?amt > 50000)
  ?claim :provider ?prov .
  ?prov :flaggedCount ?flags .
  FILTER(?flags > 3)
}

But they fail at semantic similarity: "Find claims similar to this suspicious one" requires understanding meaning, not just matching predicates.

The Problem with Pure Neural Systems

LLMs and embedding models excel at semantic understanding:

// Find semantically similar claims
const similar = embeddings.findSimilar('CLM001', 10, 0.85)

But they hallucinate, have no audit trail, and can't explain their reasoning.

The Neuro-Symbolic Solution

rust-kgdb combines both: Use embeddings for semantic discovery, symbolic reasoning for provable conclusions.

+-------------------------------------------------------------------------+
|                    NEURO-SYMBOLIC PIPELINE                               |
|                                                                          |
|   +--------------+      +--------------+      +--------------+         |
|   |   NEURAL     |      |   SYMBOLIC   |      |   NEURAL     |         |
|   |  (Discovery) | ---> |  (Reasoning) | ---> |  (Explain)   |         |
|   +--------------+      +--------------+      +--------------+         |
|                                                                          |
|   "Find similar"        "Apply rules"         "Summarize for           |
|   Embeddings search     Datalog inference     human consumption"       |
|   HNSW index            Semi-naive eval       LLM generation           |
|   Sub-ms latency        Deterministic         Cryptographic proof      |
+-------------------------------------------------------------------------+

Why 1-Hop Embeddings Matter

The ARCADE (Adaptive Relation-Aware Cache for Dynamic Embeddings) algorithm provides 1-hop neighbor awareness:

const service = new EmbeddingService()

// Build neighbor cache from triples
service.onTripleInsert('CLM001', 'claimant', 'P001', null)
service.onTripleInsert('P001', 'knows', 'P002', null)

// 1-hop aware similarity: finds entities connected in the graph
const neighbors = service.getNeighborsOut('P001')  // ['P002']

// Combine structural + semantic similarity
// "Find similar claims that are also connected to this claimant"

Why it matters: Pure embedding similarity finds semantically similar entities. 1-hop awareness finds entities that are both similar AND structurally connected - critical for fraud ring detection where relationships matter as much as content.

RDF2Vec: Native Graph Embeddings (State-of-the-Art)

rust-kgdb includes a state-of-the-art RDF2Vec implementation - graph embeddings natively backed into the database with automatic trigger-based upsert.

Performance Benchmarks

Why this matters: External embedding APIs (OpenAI, Cohere, Voyage) add 100-500ms network latency per call. RDF2Vec runs in-process at nanosecond speed.

Embedding Quality Metrics

Intra-class similarity (same type):  0.82-0.87 (excellent)
Inter-class similarity (different):   0.60 (good separation)
Separation ratio:                     1.36 (Grade B-C)
Dimensions:                           128-384 configurable

Native Integration with Graph Operations

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

// Initialize graph + RDF2Vec engine
const db = new GraphDB('http://example.org/insurance')
const rdf2vec = new Rdf2VecEngine()

// Load data into graph
db.loadTtl(`
  <http://example.org/CLM001> <http://example.org/claimType> "auto_collision" .
  <http://example.org/CLM001> <http://example.org/provider> <http://example.org/PRV001> .
  <http://example.org/CLM002> <http://example.org/claimType> "auto_collision" .
  <http://example.org/CLM002> <http://example.org/provider> <http://example.org/PRV002> .
`)

// Train RDF2Vec on graph structure (random walks)
const walks = [
  ["CLM001", "claimType", "auto_collision", "claimType_inverse", "CLM002"],
  ["CLM001", "provider", "PRV001"],
  ["CLM002", "provider", "PRV002"],
  // ... more walks from graph traversal
]
const result = JSON.parse(rdf2vec.train(JSON.stringify(walks)))
console.log(`Trained: ${result.vocabulary_size} entities, ${result.dimensions} dims`)

// Get embeddings
const embedding = rdf2vec.getEmbedding("CLM001")
console.log(`Embedding: [${embedding.slice(0, 5).join(', ')}...]`)

// Find similar entities
const similar = JSON.parse(rdf2vec.findSimilar(
  "CLM001",
  JSON.stringify(["CLM002", "CLM003", "CLM004"]),
  3
))
console.log('Similar claims:', similar)

Why RDF2Vec vs External APIs?

For text similarity: Use external APIs (OpenAI, Voyage, Cohere) For graph structure similarity: Use RDF2Vec (native) Best practice: Combine both in multi-vector architecture

Hybrid Benchmark: RDF2Vec + OpenAI vs RDF2Vec Only

Key insight: RDF2Vec alone achieves 87% recall on graph similarity tasks. Combined with OpenAI text embeddings, recall improves to 94% - but at significant cost and latency trade-off.

Incremental On-Demand Vector Generation

rust-kgdb generates vectors automatically when you need them:

// Automatic embedding on graph updates
const db = new GraphDB('http://example.org/claims')

// Insert triggers automatic embedding (if configured)
db.loadTtl(`<http://example.org/CLM999> <http://example.org/type> "auto_collision" .`)

// Embedding is already available - no separate API call needed
const embedding = rdf2vec.getEmbedding("http://example.org/CLM999")

Why this matters:

• No separate embedding pipeline
• No batch jobs or queues
• Real-time vector availability
• Graph changes → vectors updated automatically

Walk Configuration: Tuning RDF2Vec Performance

Random walks are how RDF2Vec learns graph structure. Configure walks to balance quality vs training time:

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

// Default configuration (production-ready)
const rdf2vec = new Rdf2VecEngine()

// Custom configuration for your use case
const rdf2vec = Rdf2VecEngine.withConfig(
  384,    // dimensions: 128-384 (higher = more expressive, slower)
  7,      // windowSize: 5-10 (context window for Word2Vec)
  15,     // walkLength: 5-20 hops per walk
  200     // walksPerNode: 50-500 walks per entity
)

Walk Configuration Impact on Performance:

How walks affect embedding quality:

• More walks → Better coverage of entity neighborhoods → Higher recall
• Longer walks → Captures distant relationships → Better for transitive patterns
• Shorter walks → Focuses on local structure → Better for immediate neighbors

Auto-Embedding Triggers: Automatic on Graph Insert/Update

RDF2Vec is default-ON - embeddings generate automatically when you modify the graph:

// Auto-embedding is configured by default
const db = new GraphDB('http://claims.example.org')

// 1. Load initial data - embeddings generated automatically
db.loadTtl(`
  <http://claims/CLM001> <http://claims/type> "auto_collision" .
  <http://claims/CLM001> <http://claims/amount> "5000" .
`)
// ✅ CLM001 embedding now available (no explicit call needed)

// 2. Update triggers re-embedding
db.insertTriple('http://claims/CLM001', 'http://claims/severity', 'high')
// ✅ CLM001 embedding updated with new relationship context

// 3. Bulk inserts batch embedding generation
db.loadTtl(largeTtlFile)
// ✅ All new entities embedded in single pass

How auto-triggers work:

Configuring triggers:

// Embed only subjects (default)
embedConfig.embedSource = 'subject'

// Embed both subject and object
embedConfig.embedSource = 'both'

// Filter by predicate (only embed for specific relationships)
embedConfig.predicateFilter = 'http://schema.org/name'

// Filter by graph (only embed in specific named graphs)
embedConfig.graphFilter = 'http://example.org/production'

Using RDF2Vec Alongside OpenAI (Multi-Provider Setup)

Best practice: Use RDF2Vec for graph structure + OpenAI for text semantics

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

// Initialize providers
const db = new GraphDB('http://example.org/claims')
const rdf2vec = new Rdf2VecEngine()
const service = new EmbeddingService()

// Register RDF2Vec (automatic, high priority for graph)
service.registerProvider('rdf2vec', rdf2vec, { priority: 100 })

// Register OpenAI (for text content)
service.registerProvider('openai', {
  apiKey: process.env.OPENAI_API_KEY,
  model: 'text-embedding-3-small'
}, { priority: 50 })

// Set default provider based on content type
service.setDefaultProvider('rdf2vec')  // Graph entities
service.setTextProvider('openai')       // Text descriptions

// Usage: RDF2Vec for entity similarity
const similarClaims = service.findSimilar('CLM001', 10)  // Uses rdf2vec

// Usage: OpenAI for text similarity
const similarText = service.findSimilarText('auto collision rear-end', 10)  // Uses openai

// Usage: Composite (RRF fusion)
const composite = service.findSimilarComposite('CLM001', 10, 0.7, 'rrf')

Provider Selection Logic:

1. RDF2Vec (default): Entity URIs, graph structure queries
2. OpenAI: Free text, natural language descriptions
3. Composite: When you need both structural + semantic similarity

Graph Update + Embedding Performance Benchmark

Real measurements on LUBM academic benchmark dataset (verified December 2025):

Performance Highlights:

• 130K+ triples/sec graph load throughput
• 68 µs embedding lookup (100% cache hit rate)
• 303 µs similarity search (k=5 nearest neighbors)
• 37 µs incremental triple insert (no full retrain needed)

Training throughput:

Incremental wins: After initial training, updates only re-embed affected entities (not full retrain).

Composite Multi-Vector Architecture

Store multiple embeddings per entity from different sources:

// Store embeddings from multiple providers
service.storeComposite('CLM001', JSON.stringify({
  rdf2vec: rdf2vec.getEmbedding("CLM001"),     // Graph structure
  openai: await openai.embed(claimText),        // Semantic text
  domain: customDomainEmbedding                 // Domain-specific
}))

// Search with aggregation strategies
const results = service.findSimilarComposite('CLM001', 10, 0.7, 'rrf')

// Aggregation options:
// - 'rrf'     : Reciprocal Rank Fusion (best for diverse sources)
// - 'max'     : Maximum score (best for high-confidence match)
// - 'voting'  : Majority consensus (best for ensemble robustness)

Composite vectors enable:

• Combine structural + semantic similarity
• Fail-over if one provider unavailable
• Domain-specific embedding fusion

Distributed Cluster Benchmark (Kubernetes)

Real measurements on Orbstack K8s: 1 coordinator + 3 executors (verified December 2025)

Distributed Performance Highlights:

• 3,272 LUBM triples distributed across 3 executors via HDRF partitioning
• 66-141ms query latency including network hops
• Multi-hop joins execute across partition boundaries
• NodePort access: http://localhost:30080/sparql

Graph → Embedding Pipeline (End-to-End):

// 1. Insert triples to distributed cluster
await fetch('http://localhost:30080/sparql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/sparql-update' },
  body: `INSERT DATA {
    <http://company/1> <http://schema.org/employee> <http://person/1> .
    <http://person/1> <http://schema.org/knows> <http://person/2> .
  }`
})  // 8 triples → 2ms distributed insert

// 2. Extract walks from graph relationships
const walks = await extractWalksFromSparql()  // Queries distributed cluster

// 3. Train RDF2Vec on walks
const rdf2vec = new Rdf2VecEngine()
rdf2vec.train(JSON.stringify(walks))  // 6 entities → 384-dim embeddings

// 4. Embeddings ready for similarity search
const similar = rdf2vec.findSimilar('http://person/1', candidates, 5)

Pipeline Throughput:

• Distributed INSERT: 2ms for 8 triples across 3 executors
• Walk extraction: Query time + client processing
• RDF2Vec training: 829ms for 1K walks
• Embedding lookup: 68µs per entity

HyperAgent Benchmark: RDF2Vec + Composite Embeddings vs LangChain/DSPy

Real benchmarks on LUBM dataset (3,272 triples, 30 classes, 23 properties). All numbers verified with actual API calls.

HyperMind vs LangChain/DSPy Capability Comparison

What this means: LangChain and DSPy are general-purpose LLM frameworks - they excel at text tasks but lack specialized graph capabilities. HyperMind is purpose-built for knowledge graphs with native SPARQL, Motif, and Datalog tools that understand graph structure.

Schema Injection: The Key Differentiator

Why vanilla LLMs fail (0%):

1. Wrap SPARQL in markdown (```sparql) - parser rejects
2. Invent predicates ("teacher" instead of "teacherOf")
3. No schema context - pure hallucination

Schema injection fixes this (+71.4 pp): LLM sees your actual ontology classes and properties. Uses real predicates instead of guessing.

HyperMind resolver adds another +14.3 pp: Fuzzy matching corrects "teacher" → "teacherOf" automatically via Levenshtein/Jaro-Winkler similarity.

Agentic Framework Accuracy (LLM WITH vs WITHOUT HyperMind)

7 LUBM queries, real API calls. 0% without schema because raw LLM outputs markdown-wrapped SPARQL that fails parsing. See HYPERMIND_BENCHMARK_REPORT.md.

Key finding: Same LLM, same questions - HyperMind's type contracts and schema injection transform unreliable LLM outputs into production-ready queries.

RDF2Vec + Composite Embedding Performance (RRF Reranking)

Why composite embeddings scale better: At 10K+ entities, RRF fusion's ranking algorithm amortizes its overhead. You get better accuracy AND faster performance compared to single-provider embeddings.

RRF (Reciprocal Rank Fusion) combines RDF2Vec (graph structure) + OpenAI/SBERT (semantic text):

• RDF2Vec captures: "CLM001 → provider → PRV001 → location → NYC"
• SBERT captures: "soft tissue injury auto collision rear-end"
• RRF merges rankings: structural + semantic similarity

Memory Retrieval Scalability

What MRR (Mean Reciprocal Rank) tells you: How often the correct answer appears in top results. 0.54 at 10K scale means correct entity typically in top 2 positions.

Why latency stays low: HNSW (Hierarchical Navigable Small World) index provides O(log n) similarity search, not O(n) brute force.

HyperMind Execution Engine Performance

Why Motif is fastest (0.04 ms): Pattern matching on pre-indexed adjacency lists. No query parsing overhead.

Why Datalog is slowest (1.56 ms): Semi-naive evaluation with stratified negation - computing transitive closures and recursive rules.

Why rust-kgdb + HyperMind for Enterprise AI

Bottom line: HyperMind isn't competing with LangChain for chat applications. It's purpose-built for structured knowledge graph operations where correctness, auditability, and performance matter.

Embedding Service: Multi-Provider Vector Search

Provider Abstraction

The EmbeddingService supports multiple embedding providers with a unified API:

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

// Initialize service (uses built-in 384-dim embeddings by default)
const service = new EmbeddingService()

// Store embeddings from any provider
service.storeVector('entity1', openaiEmbedding)    // 384-dim
service.storeVector('entity2', anthropicEmbedding) // 384-dim
service.storeVector('entity3', cohereEmbedding)    // 384-dim

// HNSW similarity search (Rust-native, sub-ms)
service.rebuildIndex()
const similar = JSON.parse(service.findSimilar('entity1', 10, 0.7))

Composite Multi-Provider Embeddings

For production deployments, combine multiple providers for robustness:

// Store embeddings from multiple providers for the same entity
service.storeComposite('CLM001', JSON.stringify({
  openai: await openai.embed('Insurance claim for soft tissue injury'),
  voyage: await voyage.embed('Insurance claim for soft tissue injury'),
  cohere: await cohere.embed('Insurance claim for soft tissue injury')
}))

// Search with aggregation strategies
const rrfResults = service.findSimilarComposite('CLM001', 10, 0.7, 'rrf')    // Reciprocal Rank Fusion
const maxResults = service.findSimilarComposite('CLM001', 10, 0.7, 'max')    // Max score
const voteResults = service.findSimilarComposite('CLM001', 10, 0.7, 'voting') // Majority voting

Provider Configuration

rust-kgdb's EmbeddingService stores and searches vectors - you bring your own embeddings from any provider. Here are examples using popular third-party libraries:

// ============================================================
// EXAMPLE: Using OpenAI embeddings (requires: npm install openai)
// ============================================================
const { OpenAI } = require('openai')  // Third-party library
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

async function getOpenAIEmbedding(text) {
  const response = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: text,
    dimensions: 384  // Match rust-kgdb's 384-dim format
  })
  return response.data[0].embedding
}

// ============================================================
// EXAMPLE: Using Voyage AI (requires: npm install voyageai)
// Note: Anthropic recommends Voyage AI for embeddings
// ============================================================
async function getVoyageEmbedding(text) {
  // Using fetch directly (no SDK required)
  const response = await fetch('https://api.voyageai.com/v1/embeddings', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VOYAGE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ input: text, model: 'voyage-2' })
  })
  const data = await response.json()
  return data.data[0].embedding.slice(0, 384)  // Truncate to 384-dim
}

// ============================================================
// EXAMPLE: Mock embeddings for testing (no external deps)
// ============================================================
function getMockEmbedding(text) {
  return new Array(384).fill(0).map((_, i) =>
    Math.sin(text.charCodeAt(i % text.length) * 0.1) * 0.5 + 0.5
  )
}

Graph Ingestion Pipeline with Embedding Triggers

Automatic Embedding on Triple Insert

Configure your pipeline to automatically generate embeddings when triples are inserted:

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

// Initialize services
const db = new GraphDB('http://insurance.org/claims')
const embeddings = new EmbeddingService()

// Embedding provider (configure with your API key)
async function getEmbedding(text) {
  // Replace with your provider (OpenAI, Voyage, Cohere, etc.)
  return new Array(384).fill(0).map(() => Math.random())
}

// Ingestion pipeline with embedding triggers
async function ingestClaim(claim) {
  // 1. Insert structured data into knowledge graph
  db.loadTtl(`
    @prefix : <http://insurance.org/> .
    :${claim.id} a :Claim ;
      :amount "${claim.amount}" ;
      :description "${claim.description}" ;
      :claimant :${claim.claimantId} ;
      :provider :${claim.providerId} .
  `, null)

  // 2. Generate and store embedding for semantic search
  const vector = await getEmbedding(claim.description)
  embeddings.storeVector(claim.id, vector)

  // 3. Update 1-hop cache for neighbor-aware search
  embeddings.onTripleInsert(claim.id, 'claimant', claim.claimantId, null)
  embeddings.onTripleInsert(claim.id, 'provider', claim.providerId, null)

  // 4. Rebuild index after batch inserts (or periodically)
  embeddings.rebuildIndex()

  return { tripleCount: db.countTriples(), embeddingStored: true }
}

// Process batch with embedding triggers
async function processBatch(claims) {
  for (const claim of claims) {
    await ingestClaim(claim)
    console.log(`Ingested: ${claim.id}`)
  }

  // Rebuild HNSW index after batch
  embeddings.rebuildIndex()
  console.log(`Index rebuilt with ${claims.length} new embeddings`)
}

Pipeline Architecture

+-------------------------------------------------------------------------+
|                    GRAPH INGESTION PIPELINE                              |
|                                                                          |
|   +---------------+     +---------------+     +---------------+        |
|   |  Data Source  |     |   Transform   |     |    Enrich     |        |
|   |  (JSON/CSV)   |---->|   (to RDF)    |---->|  (+Embeddings)|        |
|   +---------------+     +---------------+     +-------+-------+        |
|                                                       |                 |
|   +---------------------------------------------------+---------------+ |
|   |                      TRIGGERS                     |               | |
|   |  +-------------+  +-------------+  +-------------+-------------+ | |
|   |  | Embedding   |  |  1-Hop      |  |  HNSW Index               | | |
|   |  | Generation  |  |  Cache      |  |  Rebuild                  | | |
|   |  | (per entity)|  |  Update     |  |  (batch/periodic)         | | |
|   |  +-------------+  +-------------+  +---------------------------+ | |
|   +-------------------------------------------------------------------+ |
|                                       |                                 |
|                                       v                                 |
|   +-------------------------------------------------------------------+ |
|   |                      RUST CORE (NAPI-RS)                          | |
|   |  GraphDB (triples) | EmbeddingService (vectors) | HNSW (index)   | |
|   +-------------------------------------------------------------------+ |
+-------------------------------------------------------------------------+

HyperAgent Framework Components

The HyperMind agent framework provides complete infrastructure for building neuro-symbolic AI agents:

Architecture Overview

+-------------------------------------------------------------------------+
|                    HYPERAGENT FRAMEWORK                                  |
|                                                                          |
|   +-----------------------------------------------------------------+   |
|   |                       GOVERNANCE LAYER                           |   |
|   |  Policy Engine | Capability Grants | Audit Trail | Compliance   |   |
|   +-----------------------------------------------------------------+   |
|                                   |                                      |
|   +-------------------------------+---------------------------------+   |
|   |                       RUNTIME LAYER                              |   |
|   |  +--------------+    +-------+-------+    +--------------+      |   |
|   |  |  LLMPlanner  |    |  PlanExecutor |    |  WasmSandbox |      |   |
|   |  |  (Claude/GPT)|--->|  (Type-safe)  |--->|  (Isolated)  |      |   |
|   |  +--------------+    +---------------+    +------+-------+      |   |
|   +--------------------------------------------------+--------------+   |
|                                                      |                   |
|   +--------------------------------------------------+--------------+   |
|   |                       PROXY LAYER                |               |   |
|   |  Object Proxy: All tool calls flow through typed morphism layer |   |
|   |  +------------------------------------------------+-----------+ |   |
|   |  |  proxy.call('kg.sparql.query', { query })  -> BindingSet    | |   |
|   |  |  proxy.call('kg.motif.find', { pattern })  -> List<Match>   | |   |
|   |  |  proxy.call('kg.datalog.infer', { rules }) -> List<Fact>    | |   |
|   |  |  proxy.call('kg.embeddings.search', { entity }) -> Similar  | |   |
|   |  +------------------------------------------------------------+ |   |
|   +-----------------------------------------------------------------+   |
|                                                                          |
|   +-----------------------------------------------------------------+   |
|   |                       MEMORY LAYER                               |   |
|   |  Working Memory | Long-term Memory | Episodic Memory            |   |
|   |  (Current context) (Knowledge graph) (Execution history)        |   |
|   +-----------------------------------------------------------------+   |
|                                                                          |
|   +-----------------------------------------------------------------+   |
|   |                       SCOPE LAYER                                |   |
|   |  Namespace isolation | Resource limits | Capability boundaries  |   |
|   +-----------------------------------------------------------------+   |
+-------------------------------------------------------------------------+

Component Details

Governance Layer: Policy-based control over agent behavior

const agent = new AgentBuilder('compliance-agent')
  .withPolicy({
    maxExecutionTime: 30000,      // 30 second timeout
    allowedTools: ['kg.sparql.query', 'kg.datalog.infer'],
    deniedTools: ['kg.update', 'kg.delete'],  // Read-only
    auditLevel: 'full'           // Log all tool calls
  })

Runtime Layer: Type-safe plan execution

const { LLMPlanner, TOOL_REGISTRY } = require('rust-kgdb/hypermind-agent')

const planner = new LLMPlanner('claude-sonnet-4', TOOL_REGISTRY)
const plan = await planner.plan("Find suspicious claims")
// plan.steps: [{tool: 'kg.sparql.query', args: {...}}, ...]
// plan.confidence: 0.92

Proxy Layer: All Rust interactions through typed morphisms

const sandbox = new WasmSandbox({
  capabilities: ['ReadKG', 'ExecuteTool'],
  fuelLimit: 1000000
})

const proxy = sandbox.createObjectProxy({
  'kg.sparql.query': (args) => db.querySelect(args.query),
  'kg.embeddings.search': (args) => embeddings.findSimilar(args.entity, args.k, args.threshold)
})

// All calls are logged, metered, and capability-checked
const result = await proxy['kg.sparql.query']({ query: 'SELECT ?x WHERE { ?x a :Fraud }' })

Memory Layer: Context management across agent lifecycle

const agent = new AgentBuilder('investigator')
  .withMemory({
    working: { maxSize: 1024 * 1024 },  // 1MB working memory
    episodic: { retentionDays: 30 },     // 30-day execution history
    longTerm: db                          // Knowledge graph as long-term memory
  })

Scope Layer: Resource isolation and boundaries

const agent = new AgentBuilder('scoped-agent')
  .withScope({
    namespace: 'fraud-detection',
    resourceLimits: {
      maxTriples: 1000000,
      maxEmbeddings: 100000,
      maxConcurrentQueries: 10
    }
  })

Feature Overview

ThinkingReasoner: Deductive AI

The Problem: AI That Can't Show Its Work

When a fraud analyst asks your AI: "Is this circular payment pattern suspicious?"

What happens today:

• GPT-4: "Yes, this appears to be money laundering." (Confidence: high. Evidence: none.)
• Claude: "The pattern suggests fraudulent activity." (Sounds authoritative. No proof.)
• LLaMA: "Based on typical patterns..." (Based on what exactly?)

Every AI system gives confident answers. None can explain how they reached them. None can prove they're correct. None can trace the reasoning chain back to your actual data.

This is the hallucination problem at its core: AI generates conclusions without derivations.

The Solution: Proof-Carrying Outputs

What if every AI conclusion came with a cryptographic proof?

Traditional AI:
  Input: "Is Alice → Bob → Carol → Alice suspicious?"
  Output: "Yes, this is suspicious."  ← UNVERIFIED CLAIM

ThinkingReasoner:
  Input: "Is Alice → Bob → Carol → Alice suspicious?"
  Output:
    Conclusion: "Circular payment pattern detected"
    Proof Hash: a3f8c2e7...
    Derivation Chain:
      [1] OBSERVATION: Alice transfers to Bob (fact from database)
      [2] OBSERVATION: Bob transfers to Carol (fact from database)
      [3] OBSERVATION: Carol transfers to Alice (fact from database)
      [4] RULE: owl:TransitiveProperty → Alice transfers to Carol
      [5] RULE: circularPayment(A,B,C) :- A→B, B→C, C→A
      [6] CONCLUSION: circularPayment(Alice, Bob, Carol) ← VERIFIABLE

The difference: Every conclusion has a derivation chain. Every derivation step cites its source (observation or rule). Every chain can be replayed to verify correctness. No hallucinations possible.

The Mathematical Foundation

The ThinkingReasoner implements three interconnected theories:

1. Event Sourcing (Ground Truth)

// Every observation is append-only, immutable, timestamped
reasoner.observe("Alice transfers $10K to Bob", {
  subject: "http://example.org/alice",
  predicate: "http://example.org/transfers",
  object: "http://example.org/bob",
  timestamp: "2025-12-21T10:30:00Z",
  source: "banking-system-export"
})

Observations are facts from your systems. They can't be modified. They form the ground truth for all reasoning.

2. Ontology-Driven Rules (No Hardcoding)

// Load YOUR ontology - rules are auto-generated
reasoner.loadOntology(`
  @prefix owl: <http://www.w3.org/2002/07/owl#> .
  @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

  # This single line generates: transfers(A,C) :- transfers(A,B), transfers(B,C)
  :transfers a owl:TransitiveProperty .

  # This generates: relatedTo(B,A) :- relatedTo(A,B)
  :relatedTo a owl:SymmetricProperty .

  # This generates: Claim(X) :- FraudulentClaim(X)
  :FraudulentClaim rdfs:subClassOf :Claim .
`)

Rules aren't hardcoded in your application. They're derived from OWL/RDFS properties in your ontology. Change the ontology, change the rules. No code changes required.

3. Curry-Howard Correspondence (Proofs as Programs)

Every assertion A has a proof P such that:
  - P.conclusion = A
  - P.premises ⊆ (Observations ∪ DerivedFacts)
  - P.rules ⊆ OntologyRules
  - P.hash = SHA-256(P.conclusion, P.premises, P.rules)

This is the Curry-Howard correspondence: proofs are programs, propositions are types. An assertion without a proof is a type without an inhabitant—it doesn't exist.

Complete API Example

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

// Create reasoner for fraud detection domain
const reasoner = new ThinkingReasoner()

// Load insurance/fraud ontology
reasoner.loadOntology(`
  @prefix ins: <http://insurance.example.org/> .
  @prefix owl: <http://www.w3.org/2002/07/owl#> .
  @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

  # Transitivity: if A transfers to B, and B transfers to C, then A transfers to C
  ins:transfers a owl:TransitiveProperty .

  # Symmetry: if A is related to B, then B is related to A
  ins:relatedTo a owl:SymmetricProperty .

  # Hierarchy: FraudulentClaim is a subclass of Claim
  ins:FraudulentClaim rdfs:subClassOf ins:Claim .
  ins:HighRiskClaim rdfs:subClassOf ins:Claim .
`)

// Record observations from your data sources
const obs1 = reasoner.observe("Alice transfers $10K to Bob", {
  subject: "ins:alice",
  predicate: "ins:transfers",
  object: "ins:bob"
})

const obs2 = reasoner.observe("Bob transfers $9.5K to Carol", {
  subject: "ins:bob",
  predicate: "ins:transfers",
  object: "ins:carol"
})

const obs3 = reasoner.observe("Carol transfers $9K to Alice", {
  subject: "ins:carol",
  predicate: "ins:transfers",
  object: "ins:alice"
})

// Record a hypothesis (LLM-proposed, needs verification)
const hyp = reasoner.hypothesize(
  "Circular payment fraud detected",
  {
    subject: "ins:alice",
    predicate: "ins:suspectedFraud",
    object: "circular-payment-pattern",
    confidence: 0.85
  },
  [obs1, obs2, obs3]  // Supporting observations
)

// Run deduction - validates hypothesis against ontology rules
const result = reasoner.deduce()

console.log(`Rules fired: ${result.rulesFired}`)           // 6
console.log(`Derived facts: ${result.derivedFacts.length}`)  // 3
console.log(`Proofs generated: ${result.proofs.length}`)     // 3

// Get the thinking graph (for visualization)
const graph = reasoner.getThinkingGraph()

console.log(`Nodes: ${graph.nodes.length}`)      // Events + Facts
console.log(`Edges: ${graph.edges.length}`)      // Causal relationships
console.log(`Derivation steps: ${graph.derivationChain.length}`)  // 7

// Display derivation chain (like Claude's thinking, but verifiable)
for (const step of graph.derivationChain) {
  console.log(`Step ${step.step}: [${step.rule}] ${step.conclusion}`)
  if (step.premises.length > 0) {
    console.log(`  Premises: ${step.premises.join(', ')}`)
  }
}

Output: Derivation Chain

[1] Creating ThinkingContext...
    Context ID: fraud-detection-session
    Actor ID: fraud-agent-001

[2] Loading insurance ontology...
    Auto-generated 6 rules from ontology
    - Transitivity rules for ins:transfers
    - Symmetry rules for ins:relatedTo
    - SubClass inference rules

[3] Recording observations...
    Observation 1: Alice → Bob (ID: obs_001)
    Observation 2: Bob → Carol (ID: obs_002)
    Observation 3: Carol → Alice (ID: obs_003)

[4] Recording hypothesis...
    Hypothesis recorded (ID: hyp_001)
    Confidence: 0.85
    Based on observations: [obs_001, obs_002, obs_003]

[5] Running deduction...
    Deduction complete!
    - Rules fired: 6
    - Iterations: 3
    - Derived facts: 3
    - Proofs generated: 3

[6] Derivation Chain:
    Step 1: [OBSERVATION] ins:alice ins:transfers ins:bob
    Step 2: [OBSERVATION] ins:bob ins:transfers ins:carol
    Step 3: [owl:TransitiveProperty] ins:alice ins:transfers ins:carol
            Premises: [Step 1, Step 2]
    Step 4: [OBSERVATION] ins:carol ins:transfers ins:alice
    Step 5: [owl:TransitiveProperty] ins:bob ins:transfers ins:alice
            Premises: [Step 2, Step 4]
    Step 6: [owl:TransitiveProperty] ins:alice ins:transfers ins:alice
            Premises: [Step 1, Step 5]
    Step 7: [circularPayment] Circular payment detected
            Premises: [Step 1, Step 2, Step 4]
            Confidence: 0.85
            Proof Hash: a3f8c2e7...

Why This Matters

The Setup Data

The ThinkingReasoner demo uses synthetic inline ontologies:

Insurance Ontology (fraud detection):

• ins:transfers as owl:TransitiveProperty (payment chain detection)
• ins:relatedTo as owl:SymmetricProperty (relationship inference)
• ins:FraudulentClaim rdfs:subClassOf ins:Claim (type hierarchy)

Underwriting Ontology (risk assessment):

• uw:HighRiskApplicant rdfs:subClassOf uw:Applicant
• uw:employs as owl:TransitiveProperty (employment verification)
• uw:hasRiskIndicator with domain/range constraints

No external datasets required. Load your own ontology for your domain.

HyperFederate: Cross-Database Federation

The Real Problem: Your Knowledge Lives Everywhere

Here's what actually happens in enterprise AI projects:

A fraud analyst asks: "Show me high-risk customers with large account balances and unusual name patterns."

To answer this, they need:

• Risk scores from the Knowledge Graph (semantic relationships, fraud patterns)
• Account balances from Snowflake (transaction history, customer master)
• Name demographics from BigQuery (population statistics, anomaly detection)

Today's reality? Three separate queries. Manual data exports. Excel joins. Python scripts. Data engineers on standby. Days of work for a single question.

This is insane.

Your knowledge isn't siloed because you want it to be. It's siloed because no tool could query across systems... until now.

One Query. Three Sources. Real Answers.

-- The query that would take days... now takes 890ms
SELECT
  kg.person AS entity,
  kg.riskScore,
  entity_type(kg.person) AS types,           -- Semantic UDF
  similar_to(kg.person, 0.6) AS related,     -- AI-powered similarity
  sf.C_NAME AS customer_name,
  sf.C_ACCTBAL AS account_balance,
  bq.name AS popular_name,
  bq.number AS name_popularity
FROM graph_search('SELECT ?person ?riskScore WHERE { ?person :riskScore ?riskScore }') kg
JOIN snowflake_tpch.CUSTOMER sf ON CAST(kg.custKey AS INT) = sf.C_CUSTKEY
LEFT JOIN bigquery_public.usa_names bq ON LOWER(sf.C_NAME) = LOWER(bq.name)
WHERE kg.riskScore > 0.7
LIMIT 10

The analyst gets their answer in under a second. No data engineers. No ETL. No waiting.

How It Works: Heavy Lifting in Rust Core

The TypeScript SDK is intentionally thin. A thin RPC proxy. All the hard work happens in Rust:

┌─────────────────────────────────────────────────────────────────────────────────┐
│                        TypeScript SDK (Thin RPC Proxy)                          │
│  RpcFederationProxy: query(), createVirtualTable(), listCatalog(), ...          │
└─────────────────────────────────────────────────────────────────────────────────┘
                                      │ HTTP/RPC
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                          Rust HyperFederate Core                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ Apache Arrow │  │   Memory     │  │    HDRF      │  │   Category   │        │
│  │   / Flight   │  │ Acceleration │  │ Partitioner  │  │    Theory    │        │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘        │
│                                                                                 │
│  ┌─────────────────────────────────────────────────────────────────────────┐   │
│  │                    Connector Registry (5+ Sources)                       │   │
│  │  KGDB (graph_search) │ Snowflake │ BigQuery │ PostgreSQL │ MySQL        │   │
│  └─────────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────────┘

• Apache Arrow/Flight: High-performance columnar SQL engine (Rust)
• Memory Acceleration: Zero-copy data transfer for sub-second queries
• HDRF: Subject-anchored partitioning for distributed execution
• Category Theory: Tools as typed morphisms with provable correctness

Why This Matters

HyperFederate SQL Benchmarks

Performance measured on MacBook Pro 16,1 (2019) - Intel Core i9-9980HK @ 2.40GHz, 64GB DDR4. Commodity developer hardware. Production servers will see improved numbers.

Semantic UDFs (7 functions):

Table Functions (9 analytics):

Using RpcFederationProxy

const { RpcFederationProxy, ProofDAG } = require('rust-kgdb')

const federation = new RpcFederationProxy({
  endpoint: 'http://localhost:30180',
  identityId: 'risk-analyst-001'
})

// Query across KGDB + Snowflake + BigQuery in single SQL
const result = await federation.query(`
  WITH kg_risk AS (
    SELECT * FROM graph_search('
      PREFIX finance: <https://gonnect.ai/domains/finance#>
      SELECT ?person ?riskScore WHERE {
        ?person finance:riskScore ?riskScore .
        FILTER(?riskScore > 0.7)
      }
    ')
  )
  SELECT
    kg.person AS entity,
    kg.riskScore,
    -- Semantic UDFs on KG entities
    entity_type(kg.person) AS types,
    similar_to(kg.person, 0.6) AS similar_entities,
    -- Snowflake customer data
    sf.C_NAME AS customer_name,
    sf.C_ACCTBAL AS account_balance,
    -- BigQuery demographics
    bq.name AS popular_name,
    bq.number AS name_popularity
  FROM kg_risk kg
  JOIN snowflake_tpch.CUSTOMER sf ON CAST(kg.custKey AS INT) = sf.C_CUSTKEY
  LEFT JOIN bigquery_public.usa_names bq ON LOWER(sf.C_NAME) = LOWER(bq.name)
  LIMIT 10
`)

console.log(`Returned ${result.rowCount} rows in ${result.duration}ms`)
console.log(`Sources: ${result.metadata.sources.join(', ')}`)

Semantic UDFs (7 AI-Powered Functions)

Table Functions (9 Graph Analytics)

Virtual Tables (Session-Bound Materialization)

// Create virtual table from federation query
const vt = await federation.createVirtualTable('high_risk_customers', `
  SELECT kg.*, sf.C_ACCTBAL
  FROM graph_search('SELECT ?person ?riskScore WHERE {...}') kg
  JOIN snowflake.CUSTOMER sf ON ...
  WHERE kg.riskScore > 0.8
`, {
  refreshPolicy: 'on_demand',    // or 'ttl', 'on_source_change'
  ttlSeconds: 3600,
  sharedWith: ['risk-analyst-002'],
  sharedWithGroups: ['team-risk-analytics']
})

// Query without re-execution (materialized)
const filtered = await federation.queryVirtualTable(
  'high_risk_customers',
  'C_ACCTBAL > 100000'
)

Virtual Table Features:

• Session isolation (each user sees only their tables)
• Access control via sharedWith and sharedWithGroups
• Stored as RDF triples in KGDB (self-describing)
• Queryable via SPARQL for metadata

DCAT DPROD Catalog

// Register data product in catalog
const product = await federation.registerDataProduct({
  name: 'High Risk Customer Analysis',
  description: 'Cross-domain risk scoring combining KG + transactional data',
  sources: ['kgdb', 'snowflake', 'bigquery'],
  outputPort: '/api/v1/products/high-risk/query',
  schema: {
    columns: [
      { name: 'entity', type: 'STRING' },
      { name: 'riskScore', type: 'FLOAT64' },
      { name: 'accountBalance', type: 'DECIMAL(15,2)' }
    ]
  },
  quality: {
    completeness: 0.98,
    accuracy: 0.95,
    timeliness: 0.99
  },
  owner: 'team-risk-analytics'
})

// List catalog entries
const catalog = await federation.listCatalog({ owner: 'team-risk-analytics' })

ProofDAG with Federation Evidence

const proof = new ProofDAG('High-risk customers identified across 3 data sources')

// Add federation evidence to the proof
const fedNode = proof.addFederationEvidence(
  proof.rootId,
  threeWayQuery,                     // SQL query
  ['kgdb', 'snowflake', 'bigquery'], // sources
  42,                                // rowCount
  890,                               // duration (ms)
  { planHash: 'abc123', cached: false }
)

console.log(`Proof hash: ${proof.computeHash()}`)  // SHA-256 audit trail
console.log(`Verification: ${JSON.stringify(proof.verify())}`)

Category Theory Foundation

HyperFederate tools are typed morphisms following category theory:

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

// Each tool has Input → Output type signature
console.log(FEDERATION_TOOLS['federation.sql.query'])
// { input: 'FederatedQuery', output: 'RecordBatch', domain: 'federation' }

console.log(FEDERATION_TOOLS['federation.udf.call'])
// { input: 'UdfCall', output: 'UdfResult', udfs: ['similar_to', 'neighbors', ...] }

Installation

npm install rust-kgdb

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

Quick Start

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

// 1. Create knowledge graph
const db = new GraphDB('http://example.org/myapp')

// 2. Load RDF data (Turtle format)
db.loadTtl(`
  @prefix : <http://example.org/> .
  :alice :knows :bob .
  :bob :knows :charlie .
  :charlie :knows :alice .
`, null)

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

// 3. Query with SPARQL
const results = db.querySelect(`
  PREFIX : <http://example.org/>
  SELECT ?person WHERE { ?person :knows :bob }
`)
console.log('People who know Bob:', results)

// 4. Graph analytics
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:', graph.pageRank(0.15, 20))

// 5. Semantic similarity
const embeddings = new EmbeddingService()
embeddings.storeVector('alice', new Array(384).fill(0.5))
embeddings.storeVector('bob', new Array(384).fill(0.6))
embeddings.rebuildIndex()
console.log('Similar to alice:', embeddings.findSimilar('alice', 5, 0.3))

// 6. Datalog reasoning
const datalog = new DatalogProgram()
datalog.addFact(JSON.stringify({predicate:'knows', terms:['alice','bob']}))
datalog.addFact(JSON.stringify({predicate:'knows', terms:['bob','charlie']}))
datalog.addRule(JSON.stringify({
  head: {predicate:'connected', terms:['?X','?Z']},
  body: [
    {predicate:'knows', terms:['?X','?Y']},
    {predicate:'knows', terms:['?Y','?Z']}
  ]
}))
console.log('Inferred:', evaluateDatalog(datalog))

HyperMindAgent: Complete Getting Started

Here's how users actually create and interact with a HyperMindAgent:

Step 1: Create a Knowledge Graph

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

// Create in-memory knowledge graph
const db = new GraphDB('http://insurance.example.org/')

// Load your domain data with ontology
db.loadTtl(`
  @prefix ins: <http://insurance.example.org/> .
  @prefix owl: <http://www.w3.org/2002/07/owl#> .
  @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

  # Ontology: Define OWL properties (ThinkingReasoner auto-generates rules from these)
  ins:transfers a owl:TransitiveProperty .      # A→B, B→C implies A→C
  ins:relatedTo a owl:SymmetricProperty .       # A related B implies B related A
  ins:HighRiskClaim rdfs:subClassOf ins:Claim . # Subclass inference

  # Data: Actual entities
  ins:alice a ins:Customer ; ins:transfers ins:bob .
  ins:bob a ins:Customer ; ins:transfers ins:carol .
  ins:carol a ins:Customer ; ins:transfers ins:alice .
  ins:claim001 a ins:HighRiskClaim ; ins:claimedBy ins:alice .
`, null)

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

Step 2: Create the Agent (ThinkingReasoner is built-in)

// Create agent - ThinkingReasoner is automatically included (v0.8.4+)
const agent = new HyperMindAgent({
  name: 'fraud-detector',
  kg: db,
  // Optional: API key for LLM-powered natural language
  // apiKey: process.env.ANTHROPIC_API_KEY,
  // model: 'claude-sonnet-4'
})

console.log(`Agent "${agent.getName()}" created`)
console.log(`Reasoning stats:`, agent.getReasoningStats())
// { events: 0, facts: 0, rules: 6, proofs: 0, contexts: 1, actors: 1 }

Step 3: Natural Language Queries

// Ask questions in natural language
const result = await agent.call('Find customers who transfer money to each other')

console.log('Answer:', result.answer)
console.log('SPARQL generated:', result.explanation.plan?.sparql)
console.log('Audit trail:', agent.getAuditLog())

Step 4: Deductive Reasoning (Proof-Carrying AI)

// Record observations from your data sources (ground truth)
const obs1 = agent.observe('Alice transfers $10,000 to Bob', {
  subject: 'ins:alice',
  predicate: 'ins:transfers',
  object: 'ins:bob'
})

const obs2 = agent.observe('Bob transfers $9,500 to Carol', {
  subject: 'ins:bob',
  predicate: 'ins:transfers',
  object: 'ins:carol'
})

const obs3 = agent.observe('Carol transfers $9,000 to Alice', {
  subject: 'ins:carol',
  predicate: 'ins:transfers',
  object: 'ins:alice'
})

// Propose a hypothesis (LLM-suggested, needs validation)
const hypothesis = agent.hypothesize(
  'Potential circular payment fraud detected',
  {
    subject: 'ins:alice',
    predicate: 'ins:circularPaymentWith',
    object: 'ins:carol',
    confidence: 0.7
  },
  [obs1.id, obs2.id, obs3.id]  // Supporting evidence
)

// Run deduction - applies rules, generates proofs
const deduction = agent.deduce()

console.log(`Rules fired: ${deduction.rulesFired}`)
console.log(`Iterations: ${deduction.iterations}`)
console.log(`Derived facts: ${deduction.derivedFacts.length}`)
console.log(`Proofs generated: ${deduction.proofs.length}`)

// Each proof has: { id, hash, confidence, evidenceEvents, rulesApplied }
for (const proof of deduction.proofs) {
  console.log(`  Proof ${proof.hash}: confidence ${proof.confidence}`)
}

Step 5: Visualize the Thinking Graph

// Get the complete thinking graph (like Claude's thinking display)
const graph = agent.getThinkingGraph()

console.log('\n=== DERIVATION CHAIN ===')
for (const step of graph.derivationChain) {
  console.log(`Step ${step.step}: [${step.rule}]`)
  console.log(`  ${step.conclusion}`)
  if (step.premises?.length > 0) {
    console.log(`  Premises: ${step.premises.join(', ')}`)
  }
  if (step.proofHash) {
    console.log(`  Proof: ${step.proofHash}`)
  }
}

// Output:
// Step 1: [OBSERVATION]
//   Alice transfers $10,000 to Bob
// Step 2: [OBSERVATION]
//   Bob transfers $9,500 to Carol
// Step 3: [OBSERVATION]
//   Carol transfers $9,000 to Alice
// Step 4: [RULE: owl:TransitiveProperty]
//   Alice transfers to Carol (derived)
//   Premises: Step 1, Step 2
//   Proof: 92be3c44...
// Step 5: [HYPOTHESIS]
//   Potential circular payment fraud
//   Premises: Step 1, Step 2, Step 3
// Step 6: [RULE: circularPayment]
//   VALIDATED: Circular payment confirmed
//   Proof: e7ce16b0...

Complete Example File

Save as fraud-agent.js and run with node fraud-agent.js:

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

async function main() {
  // 1. Create knowledge graph with ontology + data
  const db = new GraphDB('http://insurance.example.org/')
  db.loadTtl(`
    @prefix ins: <http://insurance.example.org/> .
    @prefix owl: <http://www.w3.org/2002/07/owl#> .

    ins:transfers a owl:TransitiveProperty .
    ins:alice ins:transfers ins:bob .
    ins:bob ins:transfers ins:carol .
    ins:carol ins:transfers ins:alice .
  `, null)

  // 2. Create agent (ThinkingReasoner built-in)
  const agent = new HyperMindAgent({ name: 'fraud-detector', kg: db })

  // 3. Record observations
  agent.observe('Alice → Bob: $10K', { subject: 'alice', predicate: 'transfers', object: 'bob' })
  agent.observe('Bob → Carol: $9.5K', { subject: 'bob', predicate: 'transfers', object: 'carol' })
  agent.observe('Carol → Alice: $9K', { subject: 'carol', predicate: 'transfers', object: 'alice' })

  // 4. Run deduction
  const result = agent.deduce()
  console.log(`Derived ${result.derivedFacts.length} facts with ${result.proofs.length} proofs`)

  // 5. Show thinking graph
  const graph = agent.getThinkingGraph()
  console.log('\nDerivation Chain:')
  for (const step of graph.derivationChain) {
    console.log(`  [${step.rule}] ${step.conclusion}`)
  }
}

main().catch(console.error)

HyperMind: Where Neural Meets Symbolic

                    +===============================================+
                    |       THE HYPERMIND ARCHITECTURE              |
                    +===============================================+

                              Natural Language
                                    |
                                    v
                    +-----------------------------------+
                    |         LLM (Neural)              |
                    |   "Find circular payment patterns |
                    |    in claims from last month"     |
                    +-----------------------------------+
                                    |
                                    v
    +-----------------------------------------------------------------------+
    |                      TYPE THEORY LAYER                                |
    |  +-----------------+  +-----------------+  +-----------------+       |
    |  | TypeId System   |  | Refinement      |  | Session Types   |       |
    |  | (compile-time)  |  | Types           |  | (protocols)     |       |
    |  +-----------------+  +-----------------+  +-----------------+       |
    |                    ERRORS CAUGHT HERE, NOT RUNTIME                    |
    +-----------------------------------------------------------------------+
                                    |
                                    v
    +-----------------------------------------------------------------------+
    |                    CATEGORY THEORY LAYER                              |
    |                                                                       |
    |   kg.sparql.query     ---->    kg.motif.find    ---->    kg.datalog   |
    |   (Query -> Bindings)       (Pattern -> Matches)      (Rules -> Facts)  |
    |                                                                       |
    |            f: A -> B              g: B -> C           h: C -> D          |
    |                   g ∘ f: A -> C  (COMPOSITION IS TYPE-SAFE)           |
    +-----------------------------------------------------------------------+
                                    |
                                    v
    +-----------------------------------------------------------------------+
    |                      WASM SANDBOX LAYER                               |
    |  +-----------------------------------------------------------------+ |
    |  |                    wasmtime isolation                            | |
    |  |   * Isolated linear memory (no host access)                     | |
    |  |   * CPU fuel metering (10M ops max)                             | |
    |  |   * Capability-based security                                   | |
    |  |   * NO filesystem, NO network                                   | |
    |  +-----------------------------------------------------------------+ |
    +-----------------------------------------------------------------------+
                                    |
                                    v
    +-----------------------------------------------------------------------+
    |                     PROOF THEORY LAYER                                |
    |                                                                       |
    |   Every execution produces an ExecutionWitness:                      |
    |   { tool, input, output, hash, timestamp, duration }                 |
    |                                                                       |
    |   Curry-Howard: Types ↔ Propositions, Programs ↔ Proofs              |
    |   Result: Full audit trail for SOX/GDPR/FDA compliance               |
    +-----------------------------------------------------------------------+
                                    |
                                    v
                    +-----------------------------------+
                    |      Knowledge Graph Result       |
                    |   15 fraud patterns detected      |
                    |   with complete audit trail       |
                    +-----------------------------------+

HyperMind Architecture Deep Dive

For a complete walkthrough of the architecture, run:

node examples/hypermind-agent-architecture.js

Full System Architecture

+================================================================================+
|                    HYPERMIND NEURO-SYMBOLIC ARCHITECTURE                       |
+================================================================================+
|                                                                                |
|  +------------------------------------------------------------------------+   |
|  |                         APPLICATION LAYER                               |   |
|  |  +-------------+  +-------------+  +-------------+  +-------------+    |   |
|  |  |   Fraud     |  | Underwriting|  |  Compliance |  |   Custom    |    |   |
|  |  |  Detection  |  |   Agent     |  |   Checker   |  |   Agents    |    |   |
|  |  +------+------+  +------+------+  +------+------+  +------+------+    |   |
|  +---------+----------------+----------------+----------------+-----------+   |
|            +----------------+--------+-------+----------------+               |
|                                      |                                        |
|  +-----------------------------------+------------------------------------+   |
|  |                      HYPERMIND RUNTIME                                  |   |
|  |  +----------------+    +---------+---------+    +-----------------+    |   |
|  |  |  LLM PLANNER   |    |  PLAN EXECUTOR    |    |  WASM SANDBOX   |    |   |
|  |  | * Claude/GPT   |--->| * Type validation |--->| * Capabilities  |    |   |
|  |  | * Intent parse |    | * Morphism compose|    | * Fuel metering |    |   |
|  |  | * Tool select  |    | * Step execution  |    | * Memory limits |    |   |
|  |  +----------------+    +-------------------+    +--------+--------+    |   |
|  |                                                          |             |   |
|  |  +-------------------------------------------------------+-----------+ |   |
|  |  |                    OBJECT PROXY (gRPC-style)          |           | |   |
|  |  |  proxy.call("kg.sparql.query", args)  ----------------+           | |   |
|  |  |  proxy.call("kg.motif.find", args)    ----------------+           | |   |
|  |  |  proxy.call("kg.datalog.infer", args) ----------------+           | |   |
|  |  +-------------------------------------------------------+-----------+ |   |
|  +----------------------------------------------------------+-------------+   |
|                                                             |                 |
|  +----------------------------------------------------------+-------------+   |
|  |                       HYPERMIND TOOLS                    |              |   |
|  |  +-------------+  +-------------+  +-------------+  +---+---------+    |   |
|  |  |   SPARQL    |  |   MOTIF     |  |  DATALOG    |  | EMBEDDINGS  |    |   |
|  |  | String ->    |  | Pattern ->   |  | Rules ->     |  | Entity ->    |    |   |
|  |  | BindingSet  |  | List<Match> |  | List<Fact>  |  | List<Sim>   |    |   |
|  |  +-------------+  +-------------+  +-------------+  +-------------+    |   |
|  +------------------------------------------------------------------------+   |
|                                                                                |
|  +------------------------------------------------------------------------+   |
|  |                    rust-kgdb KNOWLEDGE GRAPH                            |   |
|  |  RDF Triples | SPARQL 1.1 | GraphFrames | Embeddings | Datalog         |   |
|  |  449ns lookups | 24 bytes/triple | 5-11x faster than RDFox             |   |
|  +------------------------------------------------------------------------+   |
+================================================================================+

Agent Execution Sequence

+================================================================================+
|              HYPERMIND AGENT EXECUTION - SEQUENCE DIAGRAM                      |
+================================================================================+
|                                                                                |
|  User          SDK           Planner        Sandbox        Proxy         KG    |
|   |             |              |              |              |            |    |
|   |  "Find suspicious claims"  |              |              |            |    |
|   |------------>|              |              |              |            |    |
|   |             | plan(prompt) |              |              |            |    |
|   |             |------------->|              |              |            |    |
|   |             |              | +--------------------------+|            |    |
|   |             |              | | LLM Reasoning:           ||            |    |
|   |             |              | | 1. Parse intent          ||            |    |
|   |             |              | | 2. Select tools          ||            |    |
|   |             |              | | 3. Validate types        ||            |    |
|   |             |              | +--------------------------+|            |    |
|   |             |   Plan{steps, confidence}   |              |            |    |
|   |             |<-------------|              |              |            |    |
|   |             | execute(plan)|              |              |            |    |
|   |             |----------------------------->              |            |    |
|   |             |              |  +------------------------+ |            |    |
|   |             |              |  | Sandbox Init:          | |            |    |
|   |             |              |  | * Capabilities: [Read] | |            |    |
|   |             |              |  | * Fuel: 1,000,000      | |            |    |
|   |             |              |  +------------------------+ |            |    |
|   |             |              |              | kg.sparql    |            |    |
|   |             |              |              |------------->|----------->|    |
|   |             |              |              |              | BindingSet |    |
|   |             |              |              |<-------------|<-----------|    |
|   |             |              |              | kg.datalog   |            |    |
|   |             |              |              |------------->|----------->|    |
|   |             |              |              |              | List<Fact> |    |
|   |             |              |              |<-------------|<-----------|    |
|   |             |   ExecutionResult{findings, witness}       |            |    |
|   |             |<-----------------------------              |            |    |
|   |  "Found 2 collusion patterns. Evidence: ..."            |            |    |
|   |<------------|              |              |              |            |    |
+================================================================================+

Architecture Components (v0.5.8+)

The TypeScript SDK exports production-ready HyperMind components. All execution flows through the WASM sandbox for complete security isolation:

const {
  // Type System (Hindley-Milner style)
  TypeId,           // Base types + refinement types (RiskScore, PolicyNumber)
  TOOL_REGISTRY,    // Tools as typed morphisms (category theory)

  // Runtime Components
  LLMPlanner,       // Natural language -> typed tool pipelines
  WasmSandbox,      // Secure WASM isolation with capability-based security
  AgentBuilder,     // Fluent builder for agent composition
  ComposedAgent,    // Executable agent with execution witness
} = require('rust-kgdb/hypermind-agent')

Example: Build a Custom Agent

const { AgentBuilder, LLMPlanner, TypeId, TOOL_REGISTRY } = require('rust-kgdb/hypermind-agent')

// Compose an agent using the builder pattern
const agent = new AgentBuilder('compliance-checker')
  .withTool('kg.sparql.query')
  .withTool('kg.datalog.infer')
  .withPlanner(new LLMPlanner('claude-sonnet-4', TOOL_REGISTRY))
  .withSandbox({
    capabilities: ['ReadKG', 'ExecuteTool'],  // No WriteKG for safety
    fuelLimit: 1000000,
    maxMemory: 64 * 1024 * 1024  // 64MB
  })
  .withHook('afterExecute', (step, result) => {
    console.log(`Completed: ${step.tool} -> ${result.length} results`)
  })
  .build()

// Execute with natural language
const result = await agent.call("Check compliance status for all vendors")
console.log(result.witness.proof_hash)  // sha256:...

HyperMind vs MCP (Model Context Protocol)

Why domain-enriched proxies beat generic function calling:

+-----------------------+----------------------+--------------------------+
| Feature               | MCP                  | HyperMind Proxy          |
+-----------------------+----------------------+--------------------------+
| Type Safety           | ❌ String only       | ✅ Full type system      |
| Domain Knowledge      | ❌ Generic           | ✅ Domain-enriched       |
| Tool Composition      | ❌ Isolated          | ✅ Morphism composition  |
| Validation            | ❌ Runtime           | ✅ Compile-time          |
| Security              | ❌ None              | ✅ WASM sandbox          |
| Audit Trail           | ❌ None              | ✅ Execution witness     |
| LLM Context           | ❌ Generic schema    | ✅ Rich domain hints     |
| Capability Control    | ❌ All or nothing    | ✅ Fine-grained caps     |
+-----------------------+----------------------+--------------------------+
| Result                | 60% accuracy         | 95%+ accuracy            |
|                       | "I think this might  | "Rule R1 matched facts   |
|                       |  be suspicious..."   |  F1,F2,F3. Proof: ..."   |
+-----------------------+----------------------+--------------------------+

The Key Insight

MCP: LLM generates query -> hope it works HyperMind: LLM selects tools -> type system validates -> guaranteed correct

// MCP APPROACH (Generic function calling)
// Tool: search_database(query: string)
// LLM generates: "SELECT * FROM claims WHERE suspicious = true"
// Result: ❌ SQL injection risk, "suspicious" column doesn't exist

// HYPERMIND APPROACH (Domain-enriched proxy)
// Tool: kg.datalog.infer with NICB fraud rules
const proxy = sandbox.createObjectProxy(tools)
const result = await proxy['kg.datalog.infer']({
  rules: ['potential_collusion', 'staged_accident']
})
// Result: ✅ Type-safe, domain-aware, auditable

Why Domain Proxies Win:

1. LLM becomes orchestrator, not executor
2. Domain knowledge reduces hallucination
3. Composition multiplies capability
4. Audit trail enables compliance
5. Security enables enterprise deployment

Why Vanilla LLMs Fail

When you ask an LLM to query a knowledge graph, it produces broken SPARQL 85% of the time:

User: "Find all professors"

Vanilla LLM Output:
+-----------------------------------------------------------------------+
| ```sparql                                                             |
| PREFIX ub: <http://swat.cse.lehigh.edu/onto/univ-bench.owl#>         |
| SELECT ?professor WHERE {                                             |
|   ?professor a ub:Faculty .   <- WRONG! Schema has "Professor"        |
| }                                                                     |
| ```                            <- Parser rejects markdown              |
|                                                                       |
| This query retrieves all faculty members from the LUBM dataset.      |
|                                ^ Explanation text breaks parsing      |
+-----------------------------------------------------------------------+
Result: ❌ PARSER ERROR - Invalid SPARQL syntax

Why it fails:

1. LLM wraps query in markdown code blocks -> parser chokes
2. LLM adds explanation text -> mixed with query syntax
3. LLM hallucinates class names -> ub:Faculty doesn't exist (it's ub:Professor)
4. LLM has no schema awareness -> guesses predicates and classes

How HyperMind Solves This

User: "Find all professors"

HyperMind Output:
+-----------------------------------------------------------------------+
| PREFIX ub: <http://swat.cse.lehigh.edu/onto/univ-bench.owl#>         |
| SELECT ?professor WHERE {                                             |
|   ?professor a ub:Professor . <- CORRECT! Schema-aware                |
| }                                                                     |
+-----------------------------------------------------------------------+
Result: ✅ 15 results returned in 2.3ms

Why it works:

1. Type-checked tools - Query must be valid SPARQL (compile-time check)
2. Schema integration - Tools know the ontology, not just the LLM
3. No text pollution - Query output is typed SPARQLQuery, not string
4. Deterministic execution - Same query, same result, always

Accuracy improvement: 0% -> 86.4% (+86 percentage points on LUBM benchmark)

HyperMind in Action: Complete Agent Conversation

This is what a real HyperMind agent interaction looks like. Run node examples/hypermind-complete-demo.js to see it yourself.

================================================================================
  THE PROBLEM WITH AI AGENTS TODAY
================================================================================

  You ask ChatGPT: "Find suspicious insurance claims in our data"
  It replies: "Based on typical fraud patterns, you should look for..."

  But wait -- it never SAW your data. It's guessing. Hallucinating.

  HYPERMIND'S INSIGHT: Use LLMs for UNDERSTANDING, symbolic systems for REASONING.

================================================================================

+------------------------------------------------------------------------+
|  SECTION 4: DATALOG REASONING                                          |
|  Rule-Based Inference Using NICB Fraud Detection Guidelines            |
+------------------------------------------------------------------------+

  RULE 1: potential_collusion(?X, ?Y, ?P)
    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)
    Source: NICB Ring Detection Guidelines

  Running Datalog Inference Engine...

  INFERRED FACTS:
  ---------------
  [!] COLLUSION DETECTED: 1 pattern(s)
        P001 <-> P002 via PROV001
  [!] STAGED ACCIDENT INDICATORS: 3 pattern(s)
        P001 via PROV001
        P002 via PROV001
        P005 via PROV001

+------------------------------------------------------------------------+
|  SECTION 5: HYPERMIND AGENT INTERACTION                                |
|  Natural Language Interface - The Power of Neuro-Symbolic AI           |
+------------------------------------------------------------------------+

  ========================================================================
  USER PROMPT: "Which claims look suspicious and why should I investigate them?"
  ========================================================================

  Agent Reasoning:
  1. Decomposing query: "suspicious claims" -> need risk indicators
  2. Selecting tools: GraphFrame (network), Embeddings (similarity), Datalog (rules)
  3. Type checking: All tools compatible (Graph -> Analysis -> Inference)
  4. Executing pipeline...

  ========================================================================
  AGENT RESPONSE:
  ========================================================================

  I analyzed 5 claims across 3 providers and found 2 CRITICAL fraud indicators:

  [CRITICAL] FINDING 1: COLLUSION RING (Confidence: 95%)
  --------------------------------------------------------
  Claimants:    John Smith (P001) + Jane Doe (P002)
  Provider:     Quick Care Rehabilitation Clinic
  Evidence:
    - Both filed soft tissue claims within 3 days of each other
    - Both live at 123 Main St (shared address)
    - Both have elevated risk scores (0.85, 0.72)

  Rule Triggered: NICB Collusion Pattern
    potential_collusion(P001, P002, PROV001) <- knows AND same_provider AND same_address

  Recommendation: IMMEDIATE SIU REFERRAL

  EXECUTION WITNESS (Proof Theory - Audit Trail):
  ------------------------------------------------
  Timestamp:  2024-12-14T23:15:00Z
  Agent:      fraud-investigator
  Tools:
    - kg.graphframe.triangles: 1 triangle detected
    - kg.embeddings.search: 3 clusters found
    - kg.datalog.infer: 3 fraud patterns derived
  Proof Hash: sha256:a3f2b8c9d1e4...

  ========================================================================
  USER FOLLOW-UP: "Show me the rule that detected the collusion"
  ========================================================================

  Agent Response:

  The collusion was detected by this NICB-derived Datalog rule:

  +----------------------------------------------------------------------+
  |  RULE: potential_collusion(?X, ?Y, ?P)                               |
  |                                                                      |
  |  IF:                                                                 |
  |    claimant(?X)           <- John Smith is a claimant               |
  |    claimant(?Y)           <- Jane Doe is a claimant                 |
  |    provider(?P)           <- Quick Care is a provider               |
  |    claims_with(?X, ?P)    <- John filed claim with Quick Care       |
  |    claims_with(?Y, ?P)    <- Jane filed claim with Quick Care       |
  |    knows(?X, ?Y)          <- John and Jane know each other          |
  |                                                                      |
  |  THEN:                                                               |
  |    potential_collusion(P001, P002, PROV001)                         |
  |                                                                      |
  |  CONFIDENCE: 100% (all facts verified in knowledge graph)           |
  +----------------------------------------------------------------------+

  This derivation is 100% deterministic and auditable.
  A regulator can verify this finding by checking the rule against the facts.

The Key Difference:

• Vanilla LLM: "Some claims may be suspicious" (no data access, no proof)
• HyperMind: Specific findings + rule derivations + cryptographic audit trail

Try it yourself:

node examples/hypermind-complete-demo.js  # Full 7-section demo
node examples/fraud-detection-agent.js    # Fraud detection pipeline
node examples/underwriting-agent.js       # Underwriting pipeline

Mathematical Foundations

We don't "vibe code" AI agents. Every tool is a mathematical morphism with provable properties.

Type Theory: Compile-Time Validation

// Refinement types catch errors BEFORE execution
type RiskScore = number & { __refinement: '0 ≤ x ≤ 1' }
type PolicyNumber = string & { __refinement: '/^POL-\\d{9}$/' }
type CreditScore = number & { __refinement: '300 ≤ x ≤ 850' }

// Framework validates at construction, not runtime
function assessRisk(score: RiskScore): Decision {
  // score is GUARANTEED to be 0.0-1.0
  // No defensive coding needed
}

Category Theory: Safe Tool Composition

Tools are morphisms (typed arrows):

  kg.sparql.query:     Query -> BindingSet
  kg.motif.find:       Pattern -> Matches
  kg.datalog.apply:    Rules -> InferredFacts
  kg.embeddings.search: Entity -> SimilarEntities

Composition is type-checked:

  f: A -> B
  g: B -> C
  g ∘ f: A -> C  (valid only if types align)

Laws guaranteed:
  1. Identity:      id ∘ f = f = f ∘ id
  2. Associativity: (h ∘ g) ∘ f = h ∘ (g ∘ f)

Proof Theory: Auditable Execution

Every execution produces an ExecutionWitness (Curry-Howard correspondence):

{
  "tool": "kg.sparql.query",
  "input": "SELECT ?x WHERE { ?x a :Fraud }",
  "output": "[{x: 'entity001'}]",
  "inputType": "Query",
  "outputType": "BindingSet",
  "timestamp": "2024-12-14T10:30:00Z",
  "durationMs": 12,
  "hash": "sha256:a3f2c8d9..."
}

Implication: Full audit trail for SOX, GDPR, FDA 21 CFR Part 11 compliance.

Ontology Engine

rust-kgdb includes a complete ontology engine based on W3C standards.

RDFS Reasoning

# Schema
:Employee rdfs:subClassOf :Person .
:Manager rdfs:subClassOf :Employee .

# Data
:alice a :Manager .

# Inferred (automatic)
:alice a :Employee .  # via subclass chain
:alice a :Person .    # via subclass chain

OWL 2 RL Rules

SHACL Validation

:PersonShape a sh:NodeShape ;
    sh:targetClass :Person ;
    sh:property [
        sh:path :email ;
        sh:pattern "^[a-z]+@[a-z]+\\.[a-z]+$" ;
        sh:minCount 1 ;
    ] .

Production Example: Fraud Detection

Data Sources: Example patterns based on NICB (National Insurance Crime Bureau) published fraud statistics:

• Staged accidents: 20% of insurance fraud
• Provider collusion: 25% of fraud claims
• Ring operations: 40% of organized fraud

Pattern Recognition: Circular payment detection mirrors real SIU (Special Investigation Unit) methodologies from major insurers.

Pre-Steps: Dataset and Embedding Configuration

Before running the fraud detection pipeline, configure your environment:

// ============================================================
// STEP 1: Environment Configuration
// ============================================================
const { GraphDB, GraphFrame, EmbeddingService, DatalogProgram, evaluateDatalog } = require('rust-kgdb')
const { AgentBuilder, LLMPlanner, WasmSandbox, TOOL_REGISTRY } = require('rust-kgdb/hypermind-agent')

// Configure embedding provider (choose one)
const EMBEDDING_PROVIDER = process.env.EMBEDDING_PROVIDER || 'mock'
const OPENAI_API_KEY = process.env.OPENAI_API_KEY
const VOYAGE_API_KEY = process.env.VOYAGE_API_KEY

// Embedding dimension must match provider output
const EMBEDDING_DIM = 384

// ============================================================
// STEP 2: Initialize Services
// ============================================================
const db = new GraphDB('http://insurance.org/fraud-kb')
const embeddings = new EmbeddingService()

// ============================================================
// STEP 3: Configure Embedding Provider (bring your own)
// ============================================================
async function getEmbedding(text) {
  switch (EMBEDDING_PROVIDER) {
    case 'openai':
      // Requires: npm install openai
      const { OpenAI } = require('openai')
      const openai = new OpenAI({ apiKey: OPENAI_API_KEY })
      const resp = await openai.embeddings.create({
        model: 'text-embedding-3-small',
        input: text,
        dimensions: EMBEDDING_DIM
      })
      return resp.data[0].embedding

    case 'voyage':
      // Using fetch directly (no SDK required)
      const vResp = await fetch('https://api.voyageai.com/v1/embeddings', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${VOYAGE_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ input: text, model: 'voyage-2' })
      })
      const vData = await vResp.json()
      return vData.data[0].embedding.slice(0, EMBEDDING_DIM)

    default: // Mock embeddings for testing (no external deps)
      return new Array(EMBEDDING_DIM).fill(0).map((_, i) =>
        Math.sin(text.charCodeAt(i % text.length) * 0.1) * 0.5 + 0.5
      )
  }
}

// ============================================================
// STEP 4: Load Dataset with Embedding Triggers
// ============================================================
async function loadClaimsDataset() {
  // Load structured RDF data
  db.loadTtl(`
    @prefix : <http://insurance.org/> .
    @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

    # Claims
    :CLM001 a :Claim ;
      :amount "18500"^^xsd:decimal ;
      :description "Soft tissue injury from rear-end collision" ;
      :claimant :P001 ;
      :provider :PROV001 ;
      :filingDate "2024-11-15"^^xsd:date .

    :CLM002 a :Claim ;
      :amount "22300"^^xsd:decimal ;
      :description "Whiplash injury from vehicle accident" ;
      :claimant :P002 ;
      :provider :PROV001 ;
      :filingDate "2024-11-18"^^xsd:date .

    # Claimants
    :P001 a :Claimant ;
      :name "John Smith" ;
      :address "123 Main St, Miami, FL" ;
      :riskScore "0.85"^^xsd:decimal .

    :P002 a :Claimant ;
      :name "Jane Doe" ;
      :address "123 Main St, Miami, FL" ;  # Same address!
      :riskScore "0.72"^^xsd:decimal .

    # Relationships (fraud indicators)
    :P001 :knows :P002 .
    :P001 :paidTo :P002 .
    :P002 :paidTo :P003 .
    :P003 :paidTo :P001 .  # Circular payment!

    # Provider
    :PROV001 a :Provider ;
      :name "Quick Care Rehabilitation Clinic" ;
      :flagCount "4"^^xsd:integer .
  `, null)

  console.log(`[Dataset] Loaded ${db.countTriples()} triples`)

  // Generate embeddings for claims (TRIGGER)
  const claims = ['CLM001', 'CLM002']
  for (const claimId of claims) {
    const desc = db.querySelect(`
      PREFIX : <http://insurance.org/>
      SELECT ?desc WHERE { :${claimId} :description ?desc }
    `)[0]?.bindings?.desc || claimId

    const vector = await getEmbedding(desc)
    embeddings.storeVector(claimId, vector)
    console.log(`[Embedding] Stored ${claimId}: ${vector.slice(0, 3).map(v => v.toFixed(3)).join(', ')}...`)
  }

  // Update 1-hop cache (TRIGGER)
  embeddings.onTripleInsert('CLM001', 'claimant', 'P001', null)
  embeddings.onTripleInsert('CLM001', 'provider', 'PROV001', null)
  embeddings.onTripleInsert('CLM002', 'claimant', 'P002', null)
  embeddings.onTripleInsert('CLM002', 'provider', 'PROV001', null)
  embeddings.onTripleInsert('P001', 'knows', 'P002', null)
  console.log('[1-Hop Cache] Updated neighbor relationships')

  // Rebuild HNSW index
  embeddings.rebuildIndex()
  console.log('[HNSW Index] Rebuilt for similarity search')
}

// ============================================================
// STEP 5: Run Fraud Detection Pipeline
// ============================================================
async function runFraudDetection() {
  await loadClaimsDataset()

  // Graph network analysis
  const graph = new GraphFrame(
    JSON.stringify([{id:'P001'}, {id:'P002'}, {id:'P003'}]),
    JSON.stringify([
      {src:'P001', dst:'P002'},
      {src:'P002', dst:'P003'},
      {src:'P003', dst:'P001'}
    ])
  )

  const triangles = graph.triangleCount()
  console.log(`[GraphFrame] Fraud rings detected: ${triangles}`)

  // Semantic similarity search
  const similarClaims = JSON.parse(embeddings.findSimilar('CLM001', 5, 0.7))
  console.log(`[Embeddings] Claims similar to CLM001:`, similarClaims)

  // Datalog rule-based inference
  const datalog = new DatalogProgram()
  datalog.addFact(JSON.stringify({predicate:'claim', terms:['CLM001','P001','PROV001']}))
  datalog.addFact(JSON.stringify({predicate:'claim', terms:['CLM002','P002','PROV001']}))
  datalog.addFact(JSON.stringify({predicate:'related', terms:['P001','P002']}))

  datalog.addRule(JSON.stringify({
    head: {predicate:'collusion', terms:['?P1','?P2','?Prov']},
    body: [
      {predicate:'claim', terms:['?C1','?P1','?Prov']},
      {predicate:'claim', terms:['?C2','?P2','?Prov']},
      {predicate:'related', terms:['?P1','?P2']}
    ]
  }))

  const result = JSON.parse(evaluateDatalog(datalog))
  console.log('[Datalog] Collusion detected:', result.collusion)
  // Output: [["P001","P002","PROV001"]]
}

runFraudDetection()

Run it yourself:

node examples/fraud-detection-agent.js

Actual Output: ```

FRAUD DETECTION AGENT - Production Pipeline rust-kgdb v0.2.0 | Neuro-Symbolic AI Framework

[PHASE 1] Knowledge Graph Initialization

Graph URI: http://insurance.org/fraud-kb Triples: 13

[PHASE 2] Graph Network Analysis

Vertices: 7 Edges: 8 Triangles: 1 (fraud ring indicator) PageRank (central actors): - PROV001: 0.2169 - P001: 0.1418

[PHASE 3] Semantic Similarity Analysis

Embeddings stored: 5 Vector dimension: 384

[PHASE 4] Datalog Rule-Based Inference

Facts: 6 Rules: 2 Inferred facts: - Collusion: [["P001","P002","PROV001"]] - Connected: [["P001","P003"]]

====================================================================== FRAUD DETECTION REPORT - OVERALL RISK: HIGH

---

## Production Example: Underwriting

**Data Sources:** Rating factors based on [ISO (Insurance Services Office)](https://www.verisk.com/insurance/brands/iso/) industry standards:
- NAICS codes: US Census Bureau industry classification
- Territory modifiers: Based on catastrophe exposure (hurricane zones FL, earthquake CA)
- Loss ratio thresholds: Industry standard 0.70 referral trigger
- Experience modification: Standard 5/10 year breaks

**Premium Formula:** `Base Rate × Exposure × Territory Mod × Experience Mod × Loss Mod` - standard ISO methodology.

```javascript
const { GraphDB, GraphFrame, DatalogProgram, evaluateDatalog } = require('rust-kgdb')

// Load risk factors
const db = new GraphDB('http://underwriting.org/kb')
db.loadTtl(`
  @prefix : <http://underwriting.org/> .
  :BUS001 :naics "332119" ; :lossRatio "0.45" ; :territory "FL" .
  :BUS002 :naics "541512" ; :lossRatio "0.00" ; :territory "CA" .
  :BUS003 :naics "484121" ; :lossRatio "0.72" ; :territory "TX" .
`, null)

// Apply underwriting rules
const datalog = new DatalogProgram()
datalog.addFact(JSON.stringify({predicate:'business', terms:['BUS001','manufacturing','0.45']}))
datalog.addFact(JSON.stringify({predicate:'business', terms:['BUS002','tech','0.00']}))
datalog.addFact(JSON.stringify({predicate:'business', terms:['BUS003','transport','0.72']}))
datalog.addFact(JSON.stringify({predicate:'highRiskClass', terms:['transport']}))

datalog.addRule(JSON.stringify({
  head: {predicate:'referToUW', terms:['?Bus']},
  body: [
    {predicate:'business', terms:['?Bus','?Class','?LR']},
    {predicate:'highRiskClass', terms:['?Class']}
  ]
}))

datalog.addRule(JSON.stringify({
  head: {predicate:'autoApprove', terms:['?Bus']},
  body: [{predicate:'business', terms:['?Bus','tech','?LR']}]
}))

const decisions = JSON.parse(evaluateDatalog(datalog))
console.log('Auto-approve:', decisions.autoApprove)  // [["BUS002"]]
console.log('Refer to UW:', decisions.referToUW)     // [["BUS003"]]

Run it yourself:

node examples/underwriting-agent.js

Actual Output: ```

INSURANCE UNDERWRITING AGENT - Production Pipeline rust-kgdb v0.2.0 | Neuro-Symbolic AI Framework

[PHASE 2] Risk Factor Analysis

Risk network: 12 nodes, 10 edges Risk concentration (PageRank): - BUS001: 0.0561 - BUS003: 0.0561

[PHASE 3] Similar Risk Profile Matching

Risk embeddings stored: 4 Profiles similar to BUS003 (high-risk transportation): - BUS001: manufacturing, loss ratio 0.45 - BUS004: hospitality, loss ratio 0.28

[PHASE 4] Underwriting Decision Rules

Facts loaded: 6 Decision rules: 2 Automated decisions: - BUS002: AUTO-APPROVE - BUS003: REFER TO UNDERWRITER

[PHASE 5] Premium Calculation

• BUS001: $1,339,537 (STANDARD)
• BUS002: $74,155 (APPROVED)
• BUS003: $1,125,778 (REFER)

====================================================================== Applications processed: 4 | Auto-approved: 1 | Referred: 1

---

## 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) | | | +-------+-------+ +-------+-------+ +-------+-------+ | | | | | | | +-------------+-----+-------------------+ | | | | | +---------------------v-----------------------------------------+ | | | 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 | | | +---------------------------------------------------------------+ | | | | | +---------------------v-----------------------------------------+ | | | 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 v v +-------------+ +-------------+ | Claim | provider | Claim | | (CLM001) | --------------->| (CLM002) | +------+------+ +---------+-------------+ | | v v +----------------------+ | 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
 v        v
P002 ----> P003                    Interpretation: PROV001 is the hub
     ↖____/                        that connects multiple claimants.

     1 Triangle = 1 Fraud Ring

Code: Network Analysis

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

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)