@unrdf/knowledge-engine 5.0.1 → 26.4.3

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

@@ -1,317 +0,0 @@
-/**
- * @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

@@ -1,142 +0,0 @@
-/**
- * @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

@@ -1,215 +0,0 @@
-/**
- * @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(/^\?/, '');
-}