@unrdf/knowledge-engine 5.0.1 → 26.4.3

package/src/query.mjs

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

@@ -1,350 +0,0 @@
-/**
- * @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);
-    },
-  };
-}