@unrdf/knowledge-engine 5.0.1

package/src/query.mjs

@@ -0,0 +1,306 @@
+/**
+ * @file SPARQL querying utilities.
+ * @module query
+ */
+
+import { createStore } from '@unrdf/oxigraph';
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('unrdf');
+
+/**
+ * Run a SPARQL query against a store.
+ * @param {Store} store - The n3.Store to query against
+ * @param {string} sparql - The SPARQL query string
+ * @param {Object} [options] - Query options (for compatibility)
+ * @param {number} [options.limit] - Maximum number of results
+ * @returns {Promise<any>} Promise resolving to the query result
+ *
+ * @throws {Error} If query execution fails
+ *
+ * @example
+ * const store = new Store();
+ * // ... add quads to store
+ *
+ * const results = await query(store, `
+ *   SELECT ?s ?o WHERE {
+ *     ?s <http://example.org/knows> ?o
+ *   }
+ * `);
+ * console.log(results); // Array of binding objects
+ */
+export async function query(store, sparql, _options = {}) {
+  if (!store || typeof store.getQuads !== 'function') {
+    throw new TypeError('query: store must be a valid Store instance');
+  }
+  if (typeof sparql !== 'string' || !sparql.trim()) {
+    throw new TypeError('query: sparql must be a non-empty string');
+  }
+
+  return tracer.startActiveSpan('query.sparql', async span => {
+    const startTime = performance.now();
+    try {
+      const queryType = sparql.trim().split(/\s+/)[0].toUpperCase();
+      span.setAttributes({
+        'query.type': queryType,
+        'query.length': sparql.length,
+        'query.store_size': store.size,
+      });
+
+      // Convert n3.Store quads to substrate store (synchronous)
+      const quads = store.getQuads();
+      const rdfStore = createStore(Array.from(quads));
+
+      // Execute query synchronously
+      let result;
+      try {
+        const queryResult = rdfStore.query(sparql);
+
+        // Determine result type and format accordingly
+        if (Array.isArray(queryResult)) {
+          // SELECT query result (array of bindings)
+          if (
+            queryResult.length > 0 &&
+            typeof queryResult[0] === 'object' &&
+            !queryResult[0].subject
+          ) {
+            // Already formatted bindings
+            result = queryResult;
+          } else {
+            // Check query type to determine formatting
+            if (queryType === 'CONSTRUCT' || queryType === 'DESCRIBE') {
+              // Return Oxigraph store directly with quads
+              result = rdfStore;
+              span.setAttribute('query.result_count', result.size);
+            } else {
+              // SELECT - format as bindings array
+              result = queryResult.map(item => {
+                if (item instanceof Map) {
+                  // Handle Map objects from Oxigraph
+                  const bindings = {};
+                  for (const [key, val] of item.entries()) {
+                    bindings[key] =
+                      val && val.value ? val.value : val && val.toString ? val.toString() : val;
+                  }
+                  return bindings;
+                } else if (item && typeof item === 'object') {
+                  return Object.fromEntries(
+                    Object.entries(item).map(([k, v]) => [k, v && v.value ? v.value : v])
+                  );
+                }
+                return item;
+              });
+              span.setAttribute('query.result_count', result.length);
+            }
+          }
+        } else if (typeof queryResult === 'boolean') {
+          // ASK query
+          result = queryResult;
+          span.setAttribute('query.result_type', 'boolean');
+          span.setAttribute('query.result', result);
+        } else {
+          // CONSTRUCT/DESCRIBE - return rdfStore directly (it's already an Oxigraph store)
+          result = rdfStore;
+          span.setAttribute('query.result_count', result.size);
+        }
+      } catch (engineError) {
+        // If query execution fails, provide helpful error
+        throw new Error(`Query execution failed: ${engineError.message}`);
+      }
+
+      span.setStatus({ code: SpanStatusCode.OK });
+      const duration = performance.now() - startTime;
+      span.setAttribute('query.duration_ms', duration);
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error.message,
+      });
+      throw new Error(`SPARQL query failed: ${error.message}`);
+    } finally {
+      span.end();
+    }
+  });
+}
+
+/**
+ * Execute a SELECT query and return bindings.
+ * @param {Store} store - The store to query against
+ * @param {string} sparql - The SPARQL SELECT query
+ * @param {Object} [options] - Query options
+ * @returns {Promise<Array<Object>>} Promise resolving to array of binding objects
+ *
+ * @throws {Error} If query execution fails
+ *
+ * @example
+ * const bindings = await select(store, `
+ *   SELECT ?name ?age WHERE {
+ *     ?person <http://example.org/name> ?name ;
+ *              <http://example.org/age> ?age .
+ *   }
+ * `);
+ */
+export async function select(store, sparql, options = {}) {
+  const result = await query(store, sparql, options);
+  if (Array.isArray(result)) {
+    return result;
+  }
+  throw new Error('SELECT query did not return bindings');
+}
+
+/**
+ * Execute an ASK query and return boolean result.
+ * @param {Store} store - The store to query against
+ * @param {string} sparql - The SPARQL ASK query
+ * @param {Object} [options] - Query options
+ * @returns {Promise<boolean>} Promise resolving to boolean result
+ *
+ * @throws {Error} If query execution fails
+ *
+ * @example
+ * const hasData = await ask(store, `
+ *   ASK WHERE {
+ *     ?s ?p ?o .
+ *   }
+ * `);
+ */
+export async function ask(store, sparql, options = {}) {
+  const result = await query(store, sparql, options);
+  if (typeof result === 'boolean') {
+    return result;
+  }
+  throw new Error('ASK query did not return boolean result');
+}
+
+/**
+ * Execute a CONSTRUCT query and return a new store.
+ * @param {Store} store - The store to query against
+ * @param {string} sparql - The SPARQL CONSTRUCT query
+ * @param {Object} [options] - Query options
+ * @returns {Promise<Store>} Promise resolving to a new store with constructed quads
+ *
+ * @throws {Error} If query execution fails
+ *
+ * @example
+ * const constructed = await construct(store, `
+ *   CONSTRUCT {
+ *     ?person <http://example.org/type> <http://example.org/Person> .
+ *   } WHERE {
+ *     ?person <http://example.org/name> ?name .
+ *   }
+ * `);
+ */
+export async function construct(store, sparql, options = {}) {
+  const result = await query(store, sparql, options);
+  if (result && typeof result.getQuads === 'function') {
+    return result;
+  }
+  throw new Error('CONSTRUCT query did not return a store');
+}
+
+/**
+ * Execute a DESCRIBE query and return a new store.
+ * @param {Store} store - The store to query against
+ * @param {string} sparql - The SPARQL DESCRIBE query
+ * @param {Object} [options] - Query options
+ * @returns {Promise<Store>} Promise resolving to a new store with described quads
+ *
+ * @throws {Error} If query execution fails
+ *
+ * @example
+ * const described = await describe(store, `
+ *   DESCRIBE <http://example.org/alice>
+ * `);
+ */
+export async function describe(store, sparql, options = {}) {
+  const result = await query(store, sparql, options);
+  if (result && typeof result.getQuads === 'function') {
+    return result;
+  }
+  throw new Error('DESCRIBE query did not return a store');
+}
+
+/**
+ * Execute a SPARQL UPDATE operation (INSERT, DELETE, etc.).
+ * @param {Store} store - The store to update
+ * @param {string} sparql - The SPARQL UPDATE query
+ * @param {Object} [options] - Update options
+ * @returns {Promise<Store>} Promise resolving to the updated store
+ *
+ * @throws {Error} If update execution fails
+ *
+ * @example
+ * const updated = await update(store, `
+ *   INSERT DATA {
+ *     <http://example.org/alice> <http://example.org/age> "30" .
+ *   }
+ * `);
+ */
+export async function update(store, sparql, _options = {}) {
+  if (!store || typeof store.getQuads !== 'function') {
+    throw new TypeError('update: store must be a valid Store instance');
+  }
+  if (typeof sparql !== 'string' || !sparql.trim()) {
+    throw new TypeError('update: sparql must be a non-empty string');
+  }
+
+  try {
+    // Convert n3.Store to substrate store for update
+    const quads = store.getQuads();
+    const rdfStore = createStore(Array.from(quads));
+
+    // Execute update synchronously
+    rdfStore.query(sparql);
+
+    // Return the updated store
+    return store;
+  } catch (error) {
+    throw new Error(`SPARQL update failed: ${error.message}`);
+  }
+}
+
+/**
+ * Get query execution statistics.
+ * @param {Store} store - The store to query against
+ * @param {string} sparql - The SPARQL query
+ * @param {Object} [options] - Query options
+ * @returns {Promise<Object>} Promise resolving to execution statistics
+ *
+ * @example
+ * const stats = await getQueryStats(store, sparql);
+ * console.log(`Execution time: ${stats.duration}ms`);
+ * console.log(`Result count: ${stats.resultCount}`);
+ */
+export async function getQueryStats(store, sparql, options = {}) {
+  const startTime = Date.now();
+
+  try {
+    const result = await query(store, sparql, options);
+    const endTime = Date.now();
+
+    let resultCount = 0;
+    if (Array.isArray(result)) {
+      resultCount = result.length;
+    } else if (result && typeof result.getQuads === 'function') {
+      resultCount = result.size;
+    } else if (typeof result === 'boolean') {
+      resultCount = 1;
+    }
+
+    return {
+      duration: endTime - startTime,
+      resultCount,
+      success: true,
+    };
+  } catch (error) {
+    const endTime = Date.now();
+    return {
+      duration: endTime - startTime,
+      resultCount: 0,
+      success: false,
+      error: error.message,
+    };
+  }
+}

package/src/reason.mjs

@@ -0,0 +1,350 @@
+/**
+ * @file Reasoning support using N3 rules.
+ * @module reason
+ */
+
+import { Parser, Writer } from '@unrdf/core/rdf/n3-justified-only';
+import { createStore } from '@unrdf/oxigraph'; // TODO: Replace with Oxigraph Store
+
+// Dynamic import to avoid top-level await issues
+let basicQuery;
+const loadBasicQuery = async () => {
+  if (!basicQuery) {
+    const eyereasoner = await import('eyereasoner');
+    basicQuery = eyereasoner.basicQuery;
+  }
+  return basicQuery;
+};
+
+/**
+ * Run forward-chaining reasoning with N3 rules.
+ * @param {Store} store - The store containing data to reason over
+ * @param {Store|string} rules - The store or Turtle string containing N3 rules
+ * @param {Object} [options] - Reasoning options
+ * @param {boolean} [options.includeOriginal] - Include original data in result
+ * @param {number} [options.maxIterations] - Maximum number of reasoning iterations
+ * @param {boolean} [options.debug] - Enable debug output
+ * @returns {Promise<Store>} Promise resolving to a new store containing original and inferred quads
+ *
+ * @throws {Error} If reasoning fails
+ *
+ * @example
+ * const dataStore = createStore();
+ * // ... add data quads to store
+ *
+ * const rulesTtl = `
+ *   @prefix ex: <http://example.org/> .
+ *   @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ *
+ *   { ?x ex:parent ?y } => { ?x rdfs:subClassOf ?y } .
+ * `;
+ *
+ * const reasonedStore = await reason(dataStore, rulesTtl);
+ * console.log('Original quads:', dataStore.size);
+ * console.log('Reasoned quads:', reasonedStore.size);
+ */
+export async function reason(store, rules, options = {}) {
+  if (!store || typeof store.getQuads !== 'function') {
+    throw new TypeError('reason: store must be a valid Store instance');
+  }
+  if (!rules) {
+    throw new TypeError('reason: rules must be provided');
+  }
+
+  const { includeOriginal = true, _maxIterations = 100, debug = false } = options;
+
+  try {
+    // Get data quads from store
+    const dataQuads = store.getQuads();
+
+    // Convert rules to quads if needed
+    let rulesQuads;
+    if (typeof rules === 'string') {
+      // Parse Turtle rules to quads
+      const parser = new Parser();
+      rulesQuads = parser.parse(rules);
+    } else if (rules && typeof rules.getQuads === 'function') {
+      rulesQuads = rules.getQuads();
+    } else {
+      throw new TypeError('reason: rules must be a Store or Turtle string');
+    }
+
+    if (debug) {
+      console.log('Data quads:', dataQuads.length);
+      console.log('Rules quads:', rulesQuads.length);
+    }
+
+    // Run reasoning using EYE reasoner
+    // Load basicQuery dynamically to avoid top-level await issues
+    const query = await loadBasicQuery();
+
+    // Combine data and rules as EYE expects
+    const combinedQuads = [...dataQuads, ...rulesQuads];
+    const { result } = await query(combinedQuads, []);
+
+    if (debug) {
+      console.log('Result quads:', result.length);
+    }
+
+    // Create result store
+    const _resultStore = createStore(result);
+
+    // Combine original and inferred data if requested
+    if (includeOriginal) {
+      return createStore([...dataQuads, ...result]);
+    } else {
+      // Extract only inferred quads (not in original data)
+      const originalQuadSet = new Set(dataQuads.map(q => q.toString()));
+      const inferredQuads = result.filter(q => !originalQuadSet.has(q.toString()));
+      return createStore(inferredQuads);
+    }
+  } catch (error) {
+    throw new Error(`N3 reasoning failed: ${error.message}`);
+  }
+}
+
+/**
+ * Run reasoning with multiple rule sets.
+ * @param {Store} store - The store containing data to reason over
+ * @param {Array<Store|string>} rulesList - Array of stores or Turtle strings containing N3 rules
+ * @param {Object} [options] - Reasoning options
+ * @returns {Promise<Store>} Promise resolving to a new store with all reasoning results
+ *
+ * @throws {Error} If reasoning fails
+ *
+ * @example
+ * const rulesList = [
+ *   rdfsRulesTtl,
+ *   owlRulesTtl,
+ *   customRulesTtl
+ * ];
+ *
+ * const reasonedStore = await reasonMultiple(store, rulesList);
+ */
+export async function reasonMultiple(store, rulesList, options = {}) {
+  if (!store || typeof store.getQuads !== 'function') {
+    throw new TypeError('reasonMultiple: store must be a valid Store instance');
+  }
+  if (!Array.isArray(rulesList) || rulesList.length === 0) {
+    throw new TypeError('reasonMultiple: rulesList must be a non-empty array');
+  }
+
+  try {
+    let currentStore = store;
+
+    for (let i = 0; i < rulesList.length; i++) {
+      const rules = rulesList[i];
+      if (options.debug) {
+        console.log(`Applying rule set ${i + 1}/${rulesList.length}`);
+      }
+
+      currentStore = await reason(currentStore, rules, {
+        ...options,
+        includeOriginal: true, // Always include original data for subsequent rule applications
+      });
+    }
+
+    return currentStore;
+  } catch (error) {
+    throw new Error(`Multiple N3 reasoning failed: ${error.message}`);
+  }
+}
+
+/**
+ * Extract only the newly inferred quads from reasoning.
+ * @param {Store} originalStore - The original store before reasoning
+ * @param {Store} reasonedStore - The store after reasoning
+ * @returns {Store} Store containing only the newly inferred quads
+ *
+ * @example
+ * const originalStore = createStore();
+ * // ... add original quads
+ *
+ * const reasonedStore = await reason(originalStore, rules);
+ * const inferredOnly = extractInferred(originalStore, reasonedStore);
+ * console.log('Newly inferred quads:', inferredOnly.size);
+ */
+export function extractInferred(originalStore, reasonedStore) {
+  if (!originalStore || typeof originalStore.getQuads !== 'function') {
+    throw new TypeError('extractInferred: originalStore must be a valid Store instance');
+  }
+  if (!reasonedStore || typeof reasonedStore.getQuads !== 'function') {
+    throw new TypeError('extractInferred: reasonedStore must be a valid Store instance');
+  }
+
+  const originalQuads = new Set(originalStore.getQuads().map(q => q.toString()));
+  const reasonedQuads = reasonedStore.getQuads();
+
+  const inferredQuads = reasonedQuads.filter(q => !originalQuads.has(q.toString()));
+
+  return createStore(inferredQuads);
+}
+
+/**
+ * Get reasoning statistics.
+ * @param {Store} originalStore - The original store before reasoning
+ * @param {Store} reasonedStore - The store after reasoning
+ * @returns {Object} Reasoning statistics
+ *
+ * @example
+ * const stats = getReasoningStats(originalStore, reasonedStore);
+ * console.log(`Original quads: ${stats.originalCount}`);
+ * console.log(`Inferred quads: ${stats.inferredCount}`);
+ * console.log(`Total quads: ${stats.totalCount}`);
+ * console.log(`Inference ratio: ${stats.inferenceRatio}`);
+ */
+export function getReasoningStats(originalStore, reasonedStore) {
+  if (!originalStore || typeof originalStore.getQuads !== 'function') {
+    throw new TypeError('getReasoningStats: originalStore must be a valid Store instance');
+  }
+  if (!reasonedStore || typeof reasonedStore.getQuads !== 'function') {
+    throw new TypeError('getReasoningStats: reasonedStore must be a valid Store instance');
+  }
+
+  const originalCount = originalStore.size;
+  const totalCount = reasonedStore.size;
+  const inferredCount = totalCount - originalCount;
+  const inferenceRatio = originalCount > 0 ? inferredCount / originalCount : 0;
+
+  return {
+    originalCount,
+    inferredCount,
+    totalCount,
+    inferenceRatio,
+    hasInferences: inferredCount > 0,
+  };
+}
+
+/**
+ * Validate N3 rules syntax.
+ * @param {Store|string} rules - The store or Turtle string containing N3 rules
+ * @returns {Object} Validation result
+ *
+ * @example
+ * const validation = validateRules(rulesTtl);
+ * if (!validation.valid) {
+ *   console.log('Rule validation errors:', validation.errors);
+ * }
+ */
+export function validateRules(rules) {
+  if (!rules) {
+    return { valid: false, errors: ['Rules must be provided'] };
+  }
+
+  try {
+    let rulesTurtle;
+    if (typeof rules === 'string') {
+      rulesTurtle = rules;
+    } else if (rules && typeof rules.getQuads === 'function') {
+      const writer = new Writer({ format: 'Turtle' });
+      writer.addQuads(rules.getQuads());
+      rulesTurtle = writer.quadsToString(rules.getQuads());
+    } else {
+      return {
+        valid: false,
+        errors: ['Rules must be a Store or Turtle string'],
+      };
+    }
+
+    // Basic syntax validation
+    const parser = new Parser();
+    parser.parse(rulesTurtle);
+
+    return { valid: true, errors: [] };
+  } catch (error) {
+    return { valid: false, errors: [error.message] };
+  }
+}
+
+/**
+ * Create a reasoning session with persistent state.
+ * @param {Store} initialStore - Initial store state
+ * @param {Store|string} rules - N3 rules to apply
+ * @param {Object} [options] - Session options
+ * @returns {Object} Reasoning session object
+ *
+ * @example
+ * const session = createReasoningSession(store, rules);
+ *
+ * // Add new data
+ * session.addData(newQuads);
+ *
+ * // Apply reasoning
+ * await session.reason();
+ *
+ * // Get current state
+ * const currentState = session.getState();
+ */
+export function createReasoningSession(initialStore, rules, options = {}) {
+  if (!initialStore || typeof initialStore.getQuads !== 'function') {
+    throw new TypeError('createReasoningSession: initialStore must be a valid Store instance');
+  }
+  if (!rules) {
+    throw new TypeError('createReasoningSession: rules must be provided');
+  }
+
+  let currentStore = createStore(initialStore.getQuads());
+  const sessionRules = rules;
+
+  return {
+    /**
+     * Add new data to the session.
+     * @param {Array|Quad} quads - Quads to add
+     */
+    addData(quads) {
+      if (Array.isArray(quads)) {
+        currentStore.addQuads(quads);
+      } else {
+        currentStore.add(quads);
+      }
+    },
+
+    /**
+     * Remove data from the session.
+     * @param {Array|Quad} quads - Quads to remove
+     */
+    removeData(quads) {
+      if (Array.isArray(quads)) {
+        currentStore.removeQuads(quads);
+      } else {
+        currentStore.delete(quads);
+      }
+    },
+
+    /**
+     * Apply reasoning to current state.
+     * @param {Object} [reasonOptions] - Reasoning options
+     * @returns {Promise<Store>} Updated store
+     */
+    async reason(reasonOptions = {}) {
+      currentStore = await reason(currentStore, sessionRules, {
+        ...options,
+        ...reasonOptions,
+      });
+      return currentStore;
+    },
+
+    /**
+     * Get current store state.
+     * @returns {Store} Current store
+     */
+    getState() {
+      return createStore(currentStore.getQuads());
+    },
+
+    /**
+     * Reset to initial state.
+     */
+    reset() {
+      currentStore = createStore(initialStore.getQuads());
+    },
+
+    /**
+     * Get session statistics.
+     * @returns {Object} Session statistics
+     */
+    getStats() {
+      return getReasoningStats(initialStore, currentStore);
+    },
+  };
+}