@unrdf/knowledge-engine 5.0.1

package/src/knowledge-engine/knowledge-engine.mjs

@@ -0,0 +1,317 @@
+/**
+ * @file Knowledge Engine Class
+ * @module @unrdf/knowledge-engine/knowledge-engine
+ */
+
+import { z } from 'zod';
+import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+import { getBuiltinRules } from './builtin-rules.mjs';
+
+const { namedNode } = DataFactory;
+
+/**
+ * @typedef {Object} KnowledgeEngineOptions
+ * @property {import('n3').Store} store - N3 Store for RDF data
+ * @property {Array<Rule>} [rules] - Additional custom rules
+ */
+
+/**
+ * @typedef {Object} InferenceStats
+ * @property {number} triplesInferred - Number of triples inferred
+ * @property {number} iterations - Number of inference iterations
+ * @property {number} duration - Duration in milliseconds
+ */
+
+// Namespace prefixes
+const NAMESPACES = {
+  'rdf:': 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+  'rdfs:': 'http://www.w3.org/2000/01/rdf-schema#',
+  'owl:': 'http://www.w3.org/2002/07/owl#',
+};
+
+/**
+ * Knowledge Engine - Rule-based inference for RDF graphs
+ */
+export class KnowledgeEngine {
+  /**
+   * Create a new Knowledge Engine
+   * @param {KnowledgeEngineOptions} options
+   */
+  constructor(options) {
+    const schema = z.object({
+      store: z.any(),
+      rules: z.array(z.any()).optional(),
+    });
+
+    const validated = schema.parse(options);
+
+    // Validate store has required methods
+    if (
+      !validated.store ||
+      typeof validated.store.addQuad !== 'function' ||
+      typeof validated.store.getQuads !== 'function'
+    ) {
+      throw new Error('Store must have addQuad and getQuads methods');
+    }
+
+    this.store = validated.store;
+    this.rules = validated.rules || getBuiltinRules();
+  }
+
+  /**
+   * Expand prefixed URIs to full URIs
+   * @param {string} value - Prefixed or full URI
+   * @returns {string} Full URI
+   */
+  expandPrefix(value) {
+    for (const [prefix, namespace] of Object.entries(NAMESPACES)) {
+      if (value.startsWith(prefix)) {
+        return value.replace(prefix, namespace);
+      }
+    }
+    return value;
+  }
+
+  /**
+   * Run inference and materialize inferred triples into the store
+   * @returns {InferenceStats} Inference statistics
+   */
+  materialize() {
+    const startTime = Date.now();
+    let triplesInferred = 0;
+    let iterations = 0;
+    const maxIterations = 100;
+
+    let changed = true;
+    while (changed && iterations < maxIterations) {
+      changed = false;
+      iterations++;
+
+      const beforeCount = this.store.size;
+
+      for (const rule of this.rules) {
+        const newTriples = this.applyRule(rule);
+        triplesInferred += newTriples;
+        if (newTriples > 0) {
+          changed = true;
+        }
+      }
+
+      const afterCount = this.store.size;
+      const actualNew = afterCount - beforeCount;
+
+      if (actualNew === 0) {
+        changed = false;
+      }
+    }
+
+    const duration = Date.now() - startTime;
+
+    return {
+      triplesInferred,
+      iterations,
+      duration,
+    };
+  }
+
+  /**
+   * Apply a single rule to the store
+   * @param {Object} rule - Rule to apply
+   * @returns {number} Number of new triples inferred
+   */
+  applyRule(rule) {
+    let inferredCount = 0;
+    const patterns = Array.isArray(rule.pattern) ? rule.pattern : [rule.pattern];
+    const consequents = Array.isArray(rule.consequent) ? rule.consequent : [rule.consequent];
+
+    // Find all binding sets that match the pattern
+    const bindingSets = this.findBindings(patterns);
+
+    // For each binding set, generate consequent triples
+    for (const bindings of bindingSets) {
+      for (const consequent of consequents) {
+        const triple = this.instantiateConsequent(consequent, bindings);
+        if (triple && this.addTriple(triple)) {
+          inferredCount++;
+        }
+      }
+    }
+
+    return inferredCount;
+  }
+
+  /**
+   * Find all binding sets that match the patterns
+   * @param {Array<Object>} patterns - Patterns to match
+   * @returns {Array<Object>} Array of variable bindings
+   */
+  findBindings(patterns) {
+    if (patterns.length === 0) return [];
+    if (patterns.length === 1) {
+      return this.matchPattern(patterns[0]);
+    }
+
+    // Match first pattern
+    let bindings = this.matchPattern(patterns[0]);
+
+    // Join with remaining patterns
+    for (let i = 1; i < patterns.length; i++) {
+      const nextBindings = [];
+      for (const binding of bindings) {
+        const matches = this.matchPatternWithBindings(patterns[i], binding);
+        nextBindings.push(...matches);
+      }
+      bindings = nextBindings;
+    }
+
+    return bindings;
+  }
+
+  /**
+   * Match a single pattern against the store
+   * @param {Object} pattern - Pattern to match
+   * @returns {Array<Object>} Array of variable bindings
+   */
+  matchPattern(pattern) {
+    const bindings = [];
+    const subj = this.expandPrefix(pattern.subject);
+    const pred = this.expandPrefix(pattern.predicate);
+    const obj = this.expandPrefix(pattern.object);
+
+    const subjVar = subj.startsWith('?');
+    const predVar = pred.startsWith('?');
+    const objVar = obj.startsWith('?');
+
+    const quads = this.store.getQuads(
+      subjVar ? null : namedNode(subj),
+      predVar ? null : namedNode(pred),
+      objVar ? null : namedNode(obj),
+      null
+    );
+
+    for (const quad of quads) {
+      const binding = {};
+      if (subjVar) binding[subj] = quad.subject;
+      if (predVar) binding[pred] = quad.predicate;
+      if (objVar) binding[obj] = quad.object;
+      bindings.push(binding);
+    }
+
+    return bindings;
+  }
+
+  /**
+   * Match a pattern with existing bindings
+   * @param {Object} pattern - Pattern to match
+   * @param {Object} existingBindings - Existing variable bindings
+   * @returns {Array<Object>} Array of extended variable bindings
+   */
+  matchPatternWithBindings(pattern, existingBindings) {
+    const bindings = [];
+    const subj = this.expandPrefix(pattern.subject);
+    const pred = this.expandPrefix(pattern.predicate);
+    const obj = this.expandPrefix(pattern.object);
+
+    const subjVal = subj.startsWith('?') ? existingBindings[subj] : namedNode(subj);
+    const predVal = pred.startsWith('?') ? existingBindings[pred] : namedNode(pred);
+    const objVal = obj.startsWith('?') ? existingBindings[obj] : namedNode(obj);
+
+    const quads = this.store.getQuads(subjVal || null, predVal || null, objVal || null, null);
+
+    for (const quad of quads) {
+      const binding = { ...existingBindings };
+      let consistent = true;
+
+      if (subj.startsWith('?')) {
+        if (existingBindings[subj] && !quad.subject.equals(existingBindings[subj])) {
+          consistent = false;
+        } else {
+          binding[subj] = quad.subject;
+        }
+      }
+
+      if (pred.startsWith('?')) {
+        if (existingBindings[pred] && !quad.predicate.equals(existingBindings[pred])) {
+          consistent = false;
+        } else {
+          binding[pred] = quad.predicate;
+        }
+      }
+
+      if (obj.startsWith('?')) {
+        if (existingBindings[obj] && !quad.object.equals(existingBindings[obj])) {
+          consistent = false;
+        } else {
+          binding[obj] = quad.object;
+        }
+      }
+
+      if (consistent) {
+        bindings.push(binding);
+      }
+    }
+
+    return bindings;
+  }
+
+  /**
+   * Instantiate a consequent with variable bindings
+   * @param {Object} consequent - Consequent pattern
+   * @param {Object} bindings - Variable bindings
+   * @returns {Object|null} Instantiated triple or null
+   */
+  instantiateConsequent(consequent, bindings) {
+    const subj = this.expandPrefix(consequent.subject);
+    const pred = this.expandPrefix(consequent.predicate);
+    const obj = this.expandPrefix(consequent.object);
+
+    const subjTerm = subj.startsWith('?') ? bindings[subj] : namedNode(subj);
+    const predTerm = pred.startsWith('?') ? bindings[pred] : namedNode(pred);
+    const objTerm = obj.startsWith('?') ? bindings[obj] : namedNode(obj);
+
+    if (!subjTerm || !predTerm || !objTerm) {
+      return null;
+    }
+
+    return { subject: subjTerm, predicate: predTerm, object: objTerm };
+  }
+
+  /**
+   * Add a triple to the store if it doesn't already exist
+   * @param {Object} triple - Triple to add
+   * @returns {boolean} True if added, false if already exists
+   */
+  addTriple(triple) {
+    const existing = this.store.getQuads(triple.subject, triple.predicate, triple.object, null);
+    if (existing.length > 0) {
+      return false;
+    }
+    this.store.addQuad(triple.subject, triple.predicate, triple.object);
+    return true;
+  }
+
+  /**
+   * Add a custom rule to the engine
+   * @param {Rule} rule - Rule to add
+   */
+  addRule(rule) {
+    this.rules.push(rule);
+  }
+
+  /**
+   * Get all rules in the engine
+   * @returns {Array<Rule>} All rules
+   */
+  getRules() {
+    return this.rules;
+  }
+
+  /**
+   * Clear all inferred triples from the store
+   */
+  clear() {
+    // Note: This would need additional tracking to distinguish
+    // inferred triples from asserted triples
+    // For now, this is a no-op
+  }
+}

package/src/knowledge-engine/pattern-dsl.mjs

@@ -0,0 +1,142 @@
+/**
+ * @file Pattern DSL - Simple pattern parsing
+ * @module @unrdf/knowledge-engine/pattern-dsl
+ */
+
+/**
+ * Parse a simple pattern string
+ * Format: "?subject predicate ?object"
+ *
+ * @param {string} patternString - Pattern string to parse
+ * @returns {Object} Parsed pattern object
+ *
+ * @example
+ * const pattern = parsePattern("?person rdf:type foaf:Person");
+ * // Returns: { subject: '?person', predicate: 'rdf:type', object: 'foaf:Person' }
+ */
+export function parsePattern(patternString) {
+  const trimmed = patternString.trim();
+  const parts = trimmed.split(/\s+/);
+
+  if (parts.length < 3) {
+    throw new Error(
+      `Invalid pattern: "${patternString}". Expected format: "subject predicate object"`
+    );
+  }
+
+  return {
+    subject: parts[0],
+    predicate: parts[1],
+    object: parts.slice(2).join(' '),
+  };
+}
+
+/**
+ * Convert a pattern to SPARQL WHERE clause
+ *
+ * @param {Object} pattern - Pattern object
+ * @returns {string} SPARQL pattern string
+ *
+ * @example
+ * const sparql = patternToSparql({ subject: '?x', predicate: 'rdf:type', object: 'foaf:Person' });
+ * // Returns: "?x rdf:type foaf:Person ."
+ */
+export function patternToSparql(pattern) {
+  const subject = formatTerm(pattern.subject);
+  const predicate = formatTerm(pattern.predicate);
+  const object = formatTerm(pattern.object);
+
+  return `${subject} ${predicate} ${object} .`;
+}
+
+/**
+ * Format a term for SPARQL
+ *
+ * @param {string|Object} term - Term to format
+ * @returns {string} Formatted term
+ */
+function formatTerm(term) {
+  if (!term) return '?_';
+
+  if (typeof term === 'object' && term.value) {
+    return formatTerm(term.value);
+  }
+
+  const str = String(term);
+
+  if (str.startsWith('?')) {
+    return str;
+  }
+
+  if (str.startsWith('http://') || str.startsWith('https://')) {
+    return `<${str}>`;
+  }
+
+  if (str.includes(':')) {
+    return str;
+  }
+
+  return `"${str}"`;
+}
+
+/**
+ * Parse multiple patterns from a multi-line string
+ *
+ * @param {string} patternsString - Multi-line pattern string
+ * @returns {Object[]} Array of parsed patterns
+ *
+ * @example
+ * const patterns = parsePatterns(`
+ *   ?x rdf:type foaf:Person
+ *   ?x foaf:name ?name
+ * `);
+ */
+export function parsePatterns(patternsString) {
+  const lines = patternsString
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('#'));
+
+  return lines.map(parsePattern);
+}
+
+/**
+ * Build a pattern object from components
+ *
+ * @param {string} subject - Subject term
+ * @param {string} predicate - Predicate term
+ * @param {string} object - Object term
+ * @param {string} [graph] - Optional graph term
+ * @returns {Object} Pattern object
+ *
+ * @example
+ * const pattern = buildPattern('?x', 'rdf:type', 'foaf:Person');
+ */
+export function buildPattern(subject, predicate, object, graph = null) {
+  const pattern = { subject, predicate, object };
+
+  if (graph) {
+    pattern.graph = graph;
+  }
+
+  return pattern;
+}
+
+/**
+ * Validate a pattern object
+ *
+ * @param {Object} pattern - Pattern to validate
+ * @returns {boolean} True if valid
+ *
+ * @example
+ * if (isValidPattern(pattern)) {
+ *   console.log('Pattern is valid');
+ * }
+ */
+export function isValidPattern(pattern) {
+  if (!pattern || typeof pattern !== 'object') {
+    return false;
+  }
+
+  return Boolean(pattern.subject && pattern.predicate && pattern.object);
+}

package/src/knowledge-engine/pattern-matcher.mjs

@@ -0,0 +1,215 @@
+/**
+ * @file Pattern Matching - Find quads matching triple patterns
+ * @module @unrdf/knowledge-engine/pattern-matcher
+ */
+
+import { getQuads } from '@unrdf/core';
+
+/**
+ * @typedef {import('n3').Quad} Quad
+ * @typedef {import('n3').Term} Term
+ * @typedef {import('n3').Store} Store
+ */
+
+/**
+ * Match a pattern against the store
+ *
+ * @param {Store} store - RDF store
+ * @param {Object} pattern - Pattern to match
+ * @param {string|Object} [pattern.subject] - Subject pattern
+ * @param {string|Object} [pattern.predicate] - Predicate pattern
+ * @param {string|Object} [pattern.object] - Object pattern
+ * @param {string|Object} [pattern.graph] - Graph pattern
+ * @returns {Quad[]} Array of matching quads
+ *
+ * @example
+ * const matches = matchPattern(store, {
+ *   subject: null,
+ *   predicate: 'rdf:type',
+ *   object: 'foaf:Person'
+ * });
+ */
+export function matchPattern(store, pattern) {
+  const subject = pattern.subject && !isVariable(pattern.subject) ? pattern.subject : null;
+  const predicate = pattern.predicate && !isVariable(pattern.predicate) ? pattern.predicate : null;
+  const object = pattern.object && !isVariable(pattern.object) ? pattern.object : null;
+  const graph = pattern.graph && !isVariable(pattern.graph) ? pattern.graph : null;
+
+  return getQuads(store, subject, predicate, object, graph);
+}
+
+/**
+ * Match a pattern and return variable bindings
+ *
+ * @param {Store} store - RDF store
+ * @param {Object} pattern - Pattern to match
+ * @returns {Object[]} Array of binding objects
+ *
+ * @example
+ * const bindings = matchPatternWithBindings(store, {
+ *   subject: '?person',
+ *   predicate: 'rdf:type',
+ *   object: 'foaf:Person'
+ * });
+ * // Returns: [{ person: <http://example.org/alice> }, ...]
+ */
+export function matchPatternWithBindings(store, pattern) {
+  const matches = matchPattern(store, pattern);
+  const bindings = [];
+
+  for (const quad of matches) {
+    const binding = {};
+
+    if (isVariable(pattern.subject)) {
+      const varName = getVariableName(pattern.subject);
+      binding[varName] = quad.subject;
+    }
+
+    if (isVariable(pattern.predicate)) {
+      const varName = getVariableName(pattern.predicate);
+      binding[varName] = quad.predicate;
+    }
+
+    if (isVariable(pattern.object)) {
+      const varName = getVariableName(pattern.object);
+      binding[varName] = quad.object;
+    }
+
+    if (pattern.graph && isVariable(pattern.graph)) {
+      const varName = getVariableName(pattern.graph);
+      binding[varName] = quad.graph;
+    }
+
+    bindings.push(binding);
+  }
+
+  return bindings;
+}
+
+/**
+ * Check if a pattern has at least one match
+ *
+ * @param {Store} store - RDF store
+ * @param {Object} pattern - Pattern to match
+ * @returns {boolean} True if pattern matches at least one quad
+ *
+ * @example
+ * if (hasMatch(store, { subject: '?x', predicate: 'rdf:type', object: 'foaf:Person' })) {
+ *   console.log('Found at least one person');
+ * }
+ */
+export function hasMatch(store, pattern) {
+  const matches = matchPattern(store, pattern);
+  return matches.length > 0;
+}
+
+/**
+ * Match multiple patterns (AND conjunction)
+ *
+ * @param {Store} store - RDF store
+ * @param {Object[]} patterns - Array of patterns
+ * @returns {Object[]} Array of binding sets that satisfy all patterns
+ *
+ * @example
+ * const bindings = matchMultiplePatterns(store, [
+ *   { subject: '?x', predicate: 'rdf:type', object: 'foaf:Person' },
+ *   { subject: '?x', predicate: 'foaf:name', object: '?name' }
+ * ]);
+ */
+export function matchMultiplePatterns(store, patterns) {
+  if (patterns.length === 0) {
+    return [];
+  }
+
+  if (patterns.length === 1) {
+    return matchPatternWithBindings(store, patterns[0]);
+  }
+
+  let currentBindings = matchPatternWithBindings(store, patterns[0]);
+
+  for (let i = 1; i < patterns.length; i++) {
+    const pattern = patterns[i];
+    const newBindings = [];
+
+    for (const binding of currentBindings) {
+      const instantiatedPattern = instantiatePattern(pattern, binding);
+      const matches = matchPatternWithBindings(store, instantiatedPattern);
+
+      for (const match of matches) {
+        const merged = { ...binding, ...match };
+        newBindings.push(merged);
+      }
+    }
+
+    currentBindings = newBindings;
+
+    if (currentBindings.length === 0) {
+      break;
+    }
+  }
+
+  return currentBindings;
+}
+
+/**
+ * Instantiate a pattern with variable bindings
+ *
+ * @param {Object} pattern - Pattern template
+ * @param {Object} bindings - Variable bindings
+ * @returns {Object} Pattern with variables replaced
+ */
+function instantiatePattern(pattern, bindings) {
+  return {
+    subject: instantiateTerm(pattern.subject, bindings),
+    predicate: instantiateTerm(pattern.predicate, bindings),
+    object: instantiateTerm(pattern.object, bindings),
+    graph: pattern.graph ? instantiateTerm(pattern.graph, bindings) : null,
+  };
+}
+
+/**
+ * Instantiate a term with variable bindings
+ *
+ * @param {string|Object} term - Term or variable
+ * @param {Object} bindings - Variable bindings
+ * @returns {Object|string} Instantiated term
+ */
+function instantiateTerm(term, bindings) {
+  if (!isVariable(term)) {
+    return term;
+  }
+
+  const varName = getVariableName(term);
+  return bindings[varName] || term;
+}
+
+/**
+ * Check if a term is a variable
+ *
+ * @param {string|Object} term - Term to check
+ * @returns {boolean} True if term is a variable
+ */
+function isVariable(term) {
+  if (!term) return false;
+
+  if (typeof term === 'object' && term.type === 'variable') {
+    return true;
+  }
+
+  const str = String(term);
+  return str.startsWith('?');
+}
+
+/**
+ * Get variable name (remove '?' prefix)
+ *
+ * @param {string|Object} term - Variable term
+ * @returns {string} Variable name
+ */
+function getVariableName(term) {
+  if (typeof term === 'object' && term.value) {
+    return term.value.replace(/^\?/, '');
+  }
+
+  return String(term).replace(/^\?/, '');
+}