rust-kgdb 0.8.13 → 0.8.15

package/hypermind-agent.js

@@ -4958,6 +4958,269 @@ class HyperMindAgent {
     this.intentPatterns = this._buildIntentPatterns()
   }
 
+  /**
+   * 1-LINE SETUP: Create a fully configured HyperMindAgent
+   *
+   * This is the recommended way to create agents - handles all setup automatically:
+   * - Creates GraphDB and loads TTL data
+   * - Auto-detects OWL ontology from data (owl:Class, owl:*Property patterns)
+   * - Optionally trains RDF2Vec embeddings
+   * - Enables prompt optimization with schema context
+   *
+   * @example
+   * // Minimal setup (just data)
+   * const agent = await HyperMindAgent.create({
+   *   name: 'my-agent',
+   *   data: ttlData
+   * })
+   *
+   * // Full setup with all features
+   * const agent = await HyperMindAgent.create({
+   *   name: 'fraud-detector',
+   *   data: ttlData,
+   *   rdf2vec: true,           // Train embeddings automatically
+   *   promptOptimize: true,    // Enable schema-aware prompts
+   *   apiKey: process.env.OPENAI_API_KEY,
+   *   model: 'gpt-4o'
+   * })
+   *
+   * // Then just call
+   * const result = await agent.call("Who committed fraud?")
+   *
+   * @param {Object} options - Configuration options
+   * @param {string} options.name - Agent name (required)
+   * @param {string} options.data - TTL/N-Triples data to load (required)
+   * @param {string} [options.baseUri] - Base URI for GraphDB (default: auto-detected)
+   * @param {boolean} [options.rdf2vec=false] - Train RDF2Vec embeddings
+   * @param {boolean} [options.promptOptimize=true] - Enable prompt optimization
+   * @param {string} [options.apiKey] - OpenAI/Anthropic API key
+   * @param {string} [options.model] - LLM model (e.g., 'gpt-4o', 'claude-3-opus')
+   * @param {string} [options.ontology] - Custom ontology TTL (optional, auto-detected if not provided)
+   * @returns {Promise<HyperMindAgent>} Configured agent ready to use
+   */
+  static async create(options) {
+    if (!options.name) {
+      throw new Error('name is required for HyperMindAgent.create()')
+    }
+    if (!options.data) {
+      throw new Error('data (TTL/N-Triples) is required for HyperMindAgent.create()')
+    }
+
+    // 1. Create SchemaAwareGraphDB with auto-detected or provided base URI
+    const baseUri = options.baseUri || HyperMindAgent._detectBaseUri(options.data)
+    const db = new SchemaAwareGraphDB(baseUri, { autoExtract: true })
+
+    // 2. Load TTL data
+    db.loadTtl(options.data, null)
+    const tripleCount = db.countTriples()
+    console.log(`[HyperMindAgent.create] Loaded ${tripleCount} triples`)
+
+    // 3. Auto-detect OWL ontology from data (unless custom ontology provided)
+    let ontology = options.ontology
+    if (!ontology) {
+      ontology = HyperMindAgent._autoDetectOntology(db)
+      if (ontology) {
+        console.log(`[HyperMindAgent.create] Auto-detected OWL ontology from data`)
+      }
+    }
+
+    // 4. Train RDF2Vec embeddings if requested
+    // Uses native Rust loadTtlWithEmbeddings() - all embedding logic in Rust
+    let embeddingsEnabled = false
+    if (options.rdf2vec) {
+      try {
+        // Get RDF2Vec config from options (support both boolean and object)
+        const rdf2vecConfig = typeof options.rdf2vec === 'object' ? options.rdf2vec : {}
+        // Use snake_case for NAPI-RS struct field names
+        const config = {
+          vector_size: rdf2vecConfig.dimensions || options.rdf2vecDimensions || 128,
+          window_size: rdf2vecConfig.window || options.rdf2vecWindowSize || 5,
+          walk_length: rdf2vecConfig.walkLength || options.rdf2vecWalkLength || 5,
+          walks_per_node: rdf2vecConfig.walksPerNode || options.rdf2vecWalksPerEntity || 10
+        }
+
+        // Re-load data with embeddings using native Rust (efficient, parallel)
+        const loadResult = JSON.parse(db._db.loadTtlWithEmbeddings(
+          options.data,
+          null,
+          config
+        ))
+
+        if (loadResult.embeddings?.trained) {
+          embeddingsEnabled = true
+          console.log(`[HyperMindAgent.create] Trained RDF2Vec embeddings:`)
+          console.log(`    Entities: ${loadResult.embeddings.entities_embedded}`)
+          console.log(`    Dimensions: ${loadResult.embeddings.dimensions}`)
+          console.log(`    Walks: ${loadResult.embeddings.walks_generated}`)
+          console.log(`    Training time: ${loadResult.embeddings.training_time_secs?.toFixed(2)}s`)
+        }
+      } catch (e) {
+        console.warn(`[HyperMindAgent.create] RDF2Vec training skipped: ${e.message}`)
+      }
+    }
+
+    // Create wrapper for embedding operations if enabled
+    const embeddings = embeddingsEnabled ? {
+      // Delegate to native GraphDB embedding methods
+      getEmbedding: (entity) => db._db.getEmbedding(entity),
+      findSimilar: (entity, k, threshold) => {
+        try {
+          const results = JSON.parse(db._db.findSimilar(entity, k || 10))
+          if (threshold) {
+            return results.filter(r => r.similarity >= threshold)
+          }
+          return results
+        } catch (e) {
+          return []
+        }
+      },
+      search: (text, k, threshold) => {
+        // For text search, find entities that match and return similar
+        // This uses the embedding similarity from native Rust
+        const entities = db.querySelect(`SELECT ?s WHERE { ?s ?p ?o } LIMIT ${k || 10}`)
+        const results = []
+        for (const e of entities) {
+          const entity = e.bindings?.s || e.s
+          if (entity) {
+            const similar = JSON.parse(db._db.findSimilar(entity, 1))
+            if (similar.length > 0 && (!threshold || similar[0].similarity >= threshold)) {
+              results.push({ entity, similarity: similar[0]?.similarity || 0 })
+            }
+          }
+        }
+        return results.slice(0, k || 10)
+      },
+      hasEmbeddings: () => db._db.hasEmbeddings(),
+      getStats: () => JSON.parse(db._db.getEmbeddingStats())
+    } : null
+
+    // 5. Create agent with all components
+    const agent = new HyperMindAgent({
+      name: options.name,
+      kg: db,
+      embeddings: embeddings,
+      apiKey: options.apiKey,
+      model: options.model
+    })
+
+    // 6. Load ontology for reasoning rules
+    if (ontology) {
+      agent.loadOntology(ontology)
+    }
+
+    // 7. Enable prompt optimization (extract schema)
+    if (options.promptOptimize !== false) {  // Default to true
+      await agent.extractSchema()
+      console.log(`[HyperMindAgent.create] Schema extracted for prompt optimization`)
+    }
+
+    console.log(`[HyperMindAgent.create] Agent "${options.name}" ready!`)
+    return agent
+  }
+
+  /**
+   * Auto-detect base URI from TTL data
+   * Looks for common patterns like @prefix, @base, or first subject
+   * @private
+   */
+  static _detectBaseUri(data) {
+    // Try to find @base declaration
+    const baseMatch = data.match(/@base\s+<([^>]+)>/)
+    if (baseMatch) return baseMatch[1]
+
+    // Try to find first URI in data
+    const uriMatch = data.match(/<(https?:\/\/[^>#\s]+)/)
+    if (uriMatch) {
+      // Extract base (remove fragment/local part)
+      const uri = uriMatch[1]
+      const lastSlash = uri.lastIndexOf('/')
+      const lastHash = uri.lastIndexOf('#')
+      const cutPoint = Math.max(lastSlash, lastHash)
+      return cutPoint > 0 ? uri.substring(0, cutPoint + 1) : uri
+    }
+
+    return 'http://example.org/'
+  }
+
+  /**
+   * Auto-detect OWL ontology from loaded data
+   * Scans for owl:Class, owl:ObjectProperty, owl:SymmetricProperty, etc.
+   * @private
+   */
+  static _autoDetectOntology(db) {
+    const owlPatterns = []
+
+    // Query for OWL class declarations
+    try {
+      const classes = db.querySelect(`
+        SELECT ?class WHERE {
+          ?class <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Class> .
+        }
+      `)
+      for (const r of classes) {
+        const cls = r.bindings?.class || r.class
+        if (cls) owlPatterns.push(`<${cls}> a <http://www.w3.org/2002/07/owl#Class> .`)
+      }
+    } catch (e) { /* ignore */ }
+
+    // Query for OWL SymmetricProperty
+    try {
+      const symProps = db.querySelect(`
+        SELECT ?prop WHERE {
+          ?prop <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#SymmetricProperty> .
+        }
+      `)
+      for (const r of symProps) {
+        const prop = r.bindings?.prop || r.prop
+        if (prop) owlPatterns.push(`<${prop}> a <http://www.w3.org/2002/07/owl#SymmetricProperty> .`)
+      }
+    } catch (e) { /* ignore */ }
+
+    // Query for OWL TransitiveProperty
+    try {
+      const transProps = db.querySelect(`
+        SELECT ?prop WHERE {
+          ?prop <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#TransitiveProperty> .
+        }
+      `)
+      for (const r of transProps) {
+        const prop = r.bindings?.prop || r.prop
+        if (prop) owlPatterns.push(`<${prop}> a <http://www.w3.org/2002/07/owl#TransitiveProperty> .`)
+      }
+    } catch (e) { /* ignore */ }
+
+    // Query for OWL ObjectProperty
+    try {
+      const objProps = db.querySelect(`
+        SELECT ?prop WHERE {
+          ?prop <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#ObjectProperty> .
+        }
+      `)
+      for (const r of objProps) {
+        const prop = r.bindings?.prop || r.prop
+        if (prop) owlPatterns.push(`<${prop}> a <http://www.w3.org/2002/07/owl#ObjectProperty> .`)
+      }
+    } catch (e) { /* ignore */ }
+
+    // Query for OWL DatatypeProperty
+    try {
+      const dataProps = db.querySelect(`
+        SELECT ?prop WHERE {
+          ?prop <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#DatatypeProperty> .
+        }
+      `)
+      for (const r of dataProps) {
+        const prop = r.bindings?.prop || r.prop
+        if (prop) owlPatterns.push(`<${prop}> a <http://www.w3.org/2002/07/owl#DatatypeProperty> .`)
+      }
+    } catch (e) { /* ignore */ }
+
+    if (owlPatterns.length > 0) {
+      return owlPatterns.join('\n')
+    }
+    return null
+  }
+
   /**
    * Extract schema from KG (delegates to planner)
    * @returns {Object} Schema with predicates, classes, examples

package/index.d.ts

@@ -779,7 +779,75 @@ export interface TraceEntry {
  * const trace = agent.getTrace()
  * ```
  */
+/**
+ * Options for HyperMindAgent.create() - the 1-line setup method
+ */
+export interface HyperMindAgentCreateOptions {
+  /** Agent name (required) */
+  name: string
+  /** TTL/N-Triples data to load (required) */
+  data: string
+  /** Base URI for GraphDB (optional - auto-detected from data) */
+  baseUri?: string
+  /** Train RDF2Vec embeddings (default: false) */
+  rdf2vec?: boolean
+  /** RDF2Vec dimensions (default: 128) */
+  rdf2vecDimensions?: number
+  /** RDF2Vec walk length (default: 10) */
+  rdf2vecWalkLength?: number
+  /** RDF2Vec walks per entity (default: 10) */
+  rdf2vecWalksPerEntity?: number
+  /** RDF2Vec window size (default: 5) */
+  rdf2vecWindowSize?: number
+  /** RDF2Vec training epochs (default: 5) */
+  rdf2vecEpochs?: number
+  /** Enable prompt optimization with schema context (default: true) */
+  promptOptimize?: boolean
+  /** OpenAI/Anthropic API key */
+  apiKey?: string
+  /** LLM model (e.g., 'gpt-4o', 'claude-3-opus') */
+  model?: string
+  /** Custom ontology TTL (optional - auto-detected if not provided) */
+  ontology?: string
+}
+
 export class HyperMindAgent {
+  /**
+   * 1-LINE SETUP: Create a fully configured HyperMindAgent
+   *
+   * This is the recommended way to create agents - handles all setup automatically:
+   * - Creates GraphDB and loads TTL data
+   * - Auto-detects OWL ontology from data (owl:Class, owl:*Property patterns)
+   * - Optionally trains RDF2Vec embeddings
+   * - Enables prompt optimization with schema context
+   *
+   * @example
+   * ```typescript
+   * // Minimal setup (just data)
+   * const agent = await HyperMindAgent.create({
+   *   name: 'my-agent',
+   *   data: ttlData
+   * })
+   *
+   * // Full setup with all features
+   * const agent = await HyperMindAgent.create({
+   *   name: 'fraud-detector',
+   *   data: ttlData,
+   *   rdf2vec: true,           // Train embeddings automatically
+   *   promptOptimize: true,    // Enable schema-aware prompts
+   *   apiKey: process.env.OPENAI_API_KEY,
+   *   model: 'gpt-4o'
+   * })
+   *
+   * // Then just call
+   * const result = await agent.call("Who committed fraud?")
+   * ```
+   *
+   * @param options - Configuration options
+   * @returns Promise resolving to a fully configured agent
+   */
+  static create(options: HyperMindAgentCreateOptions): Promise<HyperMindAgent>
+
   /**
    * Spawn a new HyperMind agent with the given specification
    * @param spec - Agent specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.8.13",
+  "version": "0.8.15",
   "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",