rust-kgdb 0.8.12 → 0.8.13

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
 
+## [0.8.13] - 2025-12-22
+
+### 100% Verified Euroleague Example with Real Output
+
+This release certifies **100% test pass rate** on the Euroleague basketball example with actual SPARQL output, deductive reasoning, and cryptographic proofs.
+
+#### What's New
+
+| Feature | Description | Evidence |
+|---------|-------------|----------|
+| **ThinkingReasoner** | Deductive reasoning with proofs | 111 observations → 222 derived facts |
+| **RDF2Vec Embeddings** | In-memory graph embeddings | 138 entities, 128D, 1380 walks in 2.4s |
+| **Prompt Optimization** | Schema extraction for LLM context | 11 classes, 7 predicates auto-extracted |
+| **OWL Reasoning** | SymmetricProperty + TransitiveProperty | Zero hallucination - only provable facts |
+| **Derivation Chain** | Step-by-step proof traces | SHA-256 hash per derivation |
+
+#### Verified Test Results (Euroleague Example)
+
+```
+SPARQL Queries with Assertions:
+    [PASS] Teams count = 2 (BER, PAN)
+    [PASS] Players count = 22
+    [PASS] Steals count = 3 (Lessort, Mitoglou, Mattisseck)
+    [PASS] Assist events count = 8
+    [PASS] Teammate links = 111
+
+ThinkingReasoner with Deductive Reasoning:
+    Observations: 111
+    Derived Facts: 222
+    Rules Applied: 2 (SymmetricProperty + TransitiveProperty)
+
+Use Case Queries:
+    JOURNALIST: "Who made steals?" → 3 results [PASS]
+    COACH: "Who had assists?" → 8 results [PASS]
+    ANALYST: "Scoring plays?" → 26 results [PASS]
+    FAN: "Lessort's teammates?" → 8 results [PASS]
+
+TEST RESULTS: 17 PASSED, 0 FAILED - 100.0% PASS RATE
+```
+
+#### Working Examples Repository
+
+See all examples running: [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples)
+
+```bash
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples
+npm install
+npm run euroleague     # 100% pass rate
+npm run fraud          # Circular payment detection
+npm run federation     # KGDB + Snowflake + BigQuery
+```
+
+---
+
 ## [0.8.6] - 2025-12-21
 
 ### ThinkingReasoner: Verified Rust Core Demo

package/README.md

@@ -37,6 +37,61 @@ node node_modules/rust-kgdb/examples/fraud-underwriting-reallife-demo.js
 
 ---
 
+## What's New in v0.8.13
+
+**100% Verified. 100% Deterministic. 100% Honest.**
+
+We just shipped the most rigorous AI framework you'll find anywhere. Every query returns **actual SPARQL**, every conclusion has a **cryptographic proof**, and we have **17/17 tests passing** on real-world data.
+
+| Feature | What It Does | The Proof |
+|---------|--------------|-----------|
+| **ThinkingReasoner** | Deductive engine that SHOWS ITS WORK | 111 observations → 222 derived facts |
+| **RDF2Vec Embeddings** | Graph embeddings trained IN-MEMORY | 138 entities, 128D, 1380 random walks in 2.4s |
+| **Prompt Optimization** | Auto-extracts schema for LLM context | 11 classes, 7 predicates from data |
+| **OWL Reasoning** | SymmetricProperty + TransitiveProperty rules | Zero hallucination - only provable facts |
+| **Derivation Chain** | Step-by-step proof like showing math work | SHA-256 hash per derivation |
+
+### Real Output, Not Marketing Speak
+
+**See it running:** [hypermind-examples](https://github.com/gonnect-uk/hypermind-examples)
+
+```bash
+git clone https://github.com/gonnect-uk/hypermind-examples.git
+cd hypermind-examples
+npm install
+npm run euroleague
+```
+
+**Actual output from `npm run euroleague`:**
+
+```
+[5] ThinkingReasoner with Deductive Reasoning:
+    Observations: 111
+    Derived Facts: 222
+    Rules Applied: 2
+    [PASS] Derived facts = 222 (symmetric property doubles links)
+
+[6] Thinking Graph (Derivation Chain / Proofs):
+    Step 1: [OBSERVATION] grant__jerian teammateOf osman__cedi
+    Step 2: [OBSERVATION] brown__lorenzo teammateOf osman__cedi
+    ...
+    Step 8: [OBSERVATION] hernangomez__juancho teammateOf osman__cedi
+
+JOURNALIST: "Who made the defensive steals?"
+SPARQL: SELECT ?player WHERE {
+    ?e rdf:type euro:Steal .
+    ?e euro:player ?player .
+  }
+RESULTS: 3 bindings (lessort, mitoglou, mattisseck)
+[PASS] JOURNALIST: Who made the defensive steals?
+
+TEST RESULTS: 17 PASSED, 0 FAILED - 100.0% PASS RATE
+```
+
+That's **real SPARQL**, **real results**, **real proofs**. No mocking. No hardcoding. Just `npm install` and it works.
+
+---
+
 ## What's New in v0.8.7
 
 **What if every AI conclusion came with a mathematical proof?**

package/hypermind-agent.js

@@ -3281,16 +3281,19 @@ Intent types: detect_fraud, find_similar, explain, find_patterns, aggregate, gen
     if (context.sparql) return context.sparql
 
     const predicates = schema.predicates || []
+    const classes = schema.classes || []
     const prompt = context.originalPrompt || ''
+    const promptLower = prompt.toLowerCase()
 
     // Aggregate queries don't need specific predicates
     if (intent.aggregate) {
       return 'SELECT (COUNT(*) as ?count) WHERE { ?s ?p ?o }'
     }
 
-    // Use ranker to find relevant predicates from prompt
+    // STEP 1: Match prompt against PREDICATES FIRST (higher priority for relationships)
+    // This handles queries like "teammates of X" -> teammateOf predicate
     const rankedPreds = this._findRelevantPredicatesRanked
-      ? this._findRelevantPredicatesRanked(prompt.toLowerCase(), predicates, { threshold: 0.3 })
+      ? this._findRelevantPredicatesRanked(promptLower, predicates, { threshold: 0.3 })
       : []
 
     // If we have high-confidence predicate matches, use them
@@ -3309,7 +3312,33 @@ Intent types: detect_fraud, find_similar, explain, find_patterns, aggregate, gen
       return `SELECT ?s ?o WHERE { ?s <${bestPred.predicate}> ?o } LIMIT ${CONFIG.query.defaultLimit}`
     }
 
-    // If we have type-related predicates, use for class queries
+    // STEP 2: Match prompt against CLASSES (for event types like Steal, Assist)
+    // Only after predicate matching fails, check for type-filtered queries
+    const rankedClasses = this._findRelevantPredicatesRanked
+      ? this._findRelevantPredicatesRanked(promptLower, classes, { threshold: 0.4 })
+      : []
+
+    // If we have a class match, generate a type-filtered query
+    if (rankedClasses.length > 0 && rankedClasses[0].score >= 0.5) {
+      const matchedClass = rankedClasses[0]
+
+      // Look for a "player" or "agent" predicate to link events to entities
+      const playerPred = predicates.find(p =>
+        p.toLowerCase().includes('player') ||
+        p.toLowerCase().includes('agent') ||
+        p.toLowerCase().includes('actor')
+      )
+
+      if (playerPred) {
+        // Generate query like: SELECT ?player WHERE { ?event a :Steal . ?event :player ?player }
+        return `SELECT ?entity WHERE { ?event a <${matchedClass.predicate}> . ?event <${playerPred}> ?entity } LIMIT ${CONFIG.query.defaultLimit}`
+      } else {
+        // Just get entities of this type
+        return `SELECT ?entity WHERE { ?entity a <${matchedClass.predicate}> } LIMIT ${CONFIG.query.defaultLimit}`
+      }
+    }
+
+    // STEP 3: If we have type-related predicates, use for general class queries
     if (intent.query || intent.compliance) {
       const typePredsRanked = this._findRelevantPredicatesRanked
         ? this._findRelevantPredicatesRanked('type class', predicates, { threshold: 0.4 })
@@ -5299,8 +5328,40 @@ class HyperMindAgent {
 
   _generateToolArgs(tool, intent, prompt) {
     switch (tool) {
-      case 'kg.sparql.query':
+      case 'kg.sparql.query': {
+        // Use schema-aware SPARQL generation if schema API is available
+        let schema = { predicates: [], classes: [] }
+        if (this.kg && typeof this.kg.getSchema === 'function') {
+          try {
+            const schemaJson = this.kg.getSchema()
+            const parsed = JSON.parse(schemaJson)
+            schema = {
+              predicates: parsed.predicates || [],
+              classes: parsed.classes || []
+            }
+          } catch (e) {
+            // Schema not available - fall back to default
+          }
+        }
+
+        // If we have schema, use schema-aware generation via LLMPlanner
+        if (schema.predicates.length > 0 && this.planner) {
+          const context = { originalPrompt: prompt }
+          const sparql = this.planner._generateSchemaSparql(intent, schema, context)
+
+          // Validate the generated SPARQL against schema using planner's validator
+          const validation = this.planner._validateQueryPredicates(sparql, schema)
+          if (validation.warnings.length > 0) {
+            // Log validation warning but proceed
+            console.warn('[HyperMindAgent] SPARQL validation warning:', validation.warnings.map(w => w.message))
+          }
+
+          return { query: sparql }
+        }
+
+        // Fall back to hardcoded templates if no schema
         return { query: this._generateSparql(intent, prompt) }
+      }
       case 'kg.datalog.infer':
         return { rules: this._selectRules(intent) }
       case 'kg.embeddings.search':

package/index.d.ts

@@ -71,6 +71,122 @@ export class GraphDB {
    * Get app graph URI
    */
   getGraphUri(): string
+
+  /**
+   * Get extracted schema as JSON string
+   * Contains classes, predicates, OWL properties from W3C patterns
+   */
+  getSchema(): string
+
+  /**
+   * Wait for schema to be ready
+   * @returns true when schema is extracted
+   */
+  waitForSchema(): boolean
+
+  /**
+   * Get schema statistics
+   */
+  getSchemaStats(): string
+
+  /**
+   * Validate SPARQL query predicates against loaded schema
+   * @param sparql - SPARQL query to validate
+   * @returns JSON with validation results
+   */
+  validateSparql(sparql: string): string
+
+  /**
+   * Load TTL with automatic RDF2Vec embedding generation
+   *
+   * This is the recommended way to load data for HyperMindAgent:
+   * 1. Loads TTL data
+   * 2. Extracts schema from W3C patterns
+   * 3. Generates random walks over the graph
+   * 4. Trains Word2Vec embeddings
+   * 5. Stores embeddings for similarity search
+   *
+   * @param ttlContent - Turtle format RDF data
+   * @param graphName - Optional named graph URI
+   * @param embeddingConfig - Optional embedding configuration
+   * @returns JSON string with load stats including embedding info
+   */
+  loadTtlWithEmbeddings(ttlContent: string, graphName: string | null, embeddingConfig?: EmbeddingConfig | null): string
+
+  /**
+   * Get embedding vector for an entity
+   * @param entity - Entity URI
+   * @returns Vector as array of f64, or null if not found
+   */
+  getEmbedding(entity: string): number[] | null
+
+  /**
+   * Find similar entities using cosine similarity
+   * @param entity - Query entity URI
+   * @param k - Number of similar entities to return
+   * @returns JSON array of {entity, similarity} objects
+   */
+  findSimilar(entity: string, k: number): string
+
+  /**
+   * Check if embeddings are trained and available
+   */
+  hasEmbeddings(): boolean
+
+  /**
+   * Get embedding statistics
+   */
+  getEmbeddingStats(): string
+
+  /**
+   * Build HyperFederate SQL-first prompt with dynamic schema context
+   *
+   * Takes a user prompt and returns the full LLM system prompt with:
+   * - HyperFederate SQL grammar and graph_search() UDF documentation
+   * - Available schema elements (classes, predicates) from loaded data
+   * - Statistics (triple count, class count, predicate count)
+   * - Rules to prevent hallucination
+   *
+   * @param userPrompt - The user's natural language question
+   * @returns Full system prompt for LLM with schema context injected
+   *
+   * @example
+   * ```typescript
+   * const db = new GraphDB('http://example.org/')
+   * db.loadTtl(ttlData, null)
+   *
+   * // Generate prompt with schema context
+   * const systemPrompt = db.buildSqlPrompt('Who made steals?')
+   *
+   * // Send to LLM
+   * const response = await llm.chat({
+   *   messages: [{ role: 'system', content: systemPrompt }]
+   * })
+   * ```
+   */
+  buildSqlPrompt(userPrompt: string): string
+
+  /**
+   * Generate random walks from loaded graph data
+   * @param walksPerNode - Number of walks per entity (default: 10)
+   * @param walkLength - Maximum walk length (default: 5)
+   * @returns JSON array of walks
+   */
+  generateWalks(walksPerNode?: number | null, walkLength?: number | null): string
+}
+
+/**
+ * Configuration for automatic embedding generation
+ */
+export interface EmbeddingConfig {
+  /** Vector dimensionality (default: 128) */
+  vectorSize?: number | null
+  /** Window size for Word2Vec (default: 5) */
+  windowSize?: number | null
+  /** Number of walks per entity (default: 10) */
+  walksPerNode?: number | null
+  /** Maximum walk length (default: 5) */
+  walkLength?: number | null
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "description": "High-performance RDF/SPARQL database with AI agent framework and cross-database federation. GraphDB (449ns lookups, 5-11x faster than RDFox), HyperFederate (KGDB + Snowflake + BigQuery), GraphFrames analytics, Datalog reasoning, HNSW vector embeddings. HyperMindAgent for schema-aware query generation with audit trails. W3C SPARQL 1.1 compliant. Native performance via Rust + NAPI-RS.",
   "main": "index.js",
   "types": "index.d.ts",