@unrdf/knowledge-engine 5.0.1 → 26.4.3

package/src/hook-management.mjs

@@ -1,150 +0,0 @@
-/**
- * @file Standalone Hook Management Functions
- * @module hook-management
- *
- * @description
- * Provides standalone functions for hook management as expected by the README API.
- * These functions wrap the class methods for easier usage.
- */
-
-import { defineHook } from './define-hook.mjs';
-import { KnowledgeHookManager } from './knowledge-hook-manager.mjs';
-
-// Global hook manager instance for standalone functions
-let globalHookManager = null;
-
-/**
- * Initialize the global hook manager if not already initialized
- * @param {Object} options - Options for the hook manager
- * @returns {KnowledgeHookManager} The global hook manager
- */
-function getGlobalHookManager(options = {}) {
-  if (!globalHookManager) {
-    globalHookManager = new KnowledgeHookManager(options);
-  }
-  return globalHookManager;
-}
-
-/**
- * Register a knowledge hook globally
- * @param {Object} hook - The knowledge hook to register
- * @param {Object} options - Manager options (if manager needs initialization)
- * @throws {Error} If hook is invalid or already exists
- *
- * @example
- * const hook = defineHook({
- *   meta: { name: 'test-hook', description: 'Test hook' },
- *   when: { kind: 'sparql-ask', query: 'ASK { ?s ?p ?o }' },
- *   run: async (event) => console.log('Hook triggered')
- * });
- *
- * await registerHook(hook);
- */
-export async function registerHook(hook, options = {}) {
-  const manager = getGlobalHookManager(options);
-
-  // Validate hook if it's not already validated
-  const validatedHook = typeof hook === 'object' && !hook._validated ? defineHook(hook) : hook;
-
-  return manager.addKnowledgeHook(validatedHook);
-}
-
-/**
- * Deregister (remove) a knowledge hook globally
- * @param {string} hookName - The name of the hook to remove
- * @returns {boolean} True if hook was removed, false if not found
- *
- * @example
- * const removed = await deregisterHook('test-hook');
- * console.log('Hook removed:', removed);
- */
-export async function deregisterHook(hookName) {
-  if (!globalHookManager) {
-    return false;
-  }
-
-  return globalHookManager.removeKnowledgeHook(hookName);
-}
-
-/**
- * Manually evaluate a hook against given data
- * @param {Object} hook - The hook to evaluate
- * @param {Store} store - The RDF store to evaluate against
- * @param {Object} context - Additional context for evaluation
- * @returns {Object} Evaluation result
- *
- * @example
- * const result = await evaluateHook(hook, store, { timestamp: Date.now() });
- * console.log('Hook evaluation result:', result);
- */
-export async function evaluateHook(hook, store, context = {}) {
-  // Validate hook if needed
-  const validatedHook = typeof hook === 'object' && !hook._validated ? defineHook(hook) : hook;
-
-  // Create a temporary manager for evaluation
-  const tempManager = new KnowledgeHookManager({ enableKnowledgeHooks: true });
-
-  try {
-    // Add hook temporarily
-    tempManager.addKnowledgeHook(validatedHook);
-
-    // Evaluate the hook
-    const event = {
-      store,
-      context,
-      timestamp: Date.now(),
-      hookName: validatedHook.meta.name,
-    };
-
-    // Run the hook evaluation logic
-    const conditionResult = await tempManager.conditionEvaluator.isSatisfied(
-      validatedHook.when,
-      store,
-      context
-    );
-
-    event.result = conditionResult;
-    event.satisfied = conditionResult === true;
-
-    // Execute hook if condition is satisfied
-    if (event.satisfied && validatedHook.run) {
-      event.output = await validatedHook.run(event);
-    }
-
-    return event;
-  } catch (error) {
-    return {
-      error: error.message,
-      hookName: validatedHook.meta.name,
-      timestamp: Date.now(),
-    };
-  }
-}
-
-/**
- * Get all registered hooks
- * @returns {Array} Array of registered hook names
- */
-export function getRegisteredHooks() {
-  if (!globalHookManager) {
-    return [];
-  }
-
-  return Array.from(globalHookManager.knowledgeHooks.keys());
-}
-
-/**
- * Reset the global hook manager
- * Useful for testing or cleanup
- */
-export function resetGlobalHookManager() {
-  globalHookManager = null;
-}
-
-export default {
-  registerHook,
-  deregisterHook,
-  evaluateHook,
-  getRegisteredHooks,
-  resetGlobalHookManager,
-};

package/src/ken-parliment.mjs

@@ -1,119 +0,0 @@
-/**
- * @file ken-parliament-debug.mjs
- * @description Debugging version of Parliamentary Swarm Demo with Robert's Rules
- */
-
-import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
-import { createStore } from '@unrdf/oxigraph'; // TODO: Replace with Oxigraph Store
-import { TransactionManager, printReceipt } from './knowledge-engine.mjs';
-
-const { namedNode, literal, quad } = DataFactory;
-
-async function main() {
-  console.log('🏛️ Starting Parliamentary Swarm Demo (Debug Mode)...\n');
-
-  const store = createStore();
-  const tx = new TransactionManager();
-  const ex = 'http://example.org/';
-
-  // === Hooks ===
-  tx.addHook({
-    id: 'motion-must-be-seconded',
-    mode: 'pre',
-    condition: async (store, delta) => {
-      const adoptions = delta.additions.filter(q => q.predicate.value === `${ex}adoptMotion`);
-      for (const adoption of adoptions) {
-        const motion = adoption.subject;
-        const seconds = store.getQuads(motion, namedNode(`${ex}secondedBy`), null, null);
-        console.log(`🔎 Hook check: ${motion.value} has ${seconds.length} seconds in store.`);
-        if (seconds.length === 0) return false;
-      }
-      return true;
-    },
-    effect: 'veto',
-  });
-
-  tx.addHook({
-    id: 'vote-before-adoption',
-    mode: 'pre',
-    condition: async (store, delta) => {
-      const adoptions = delta.additions.filter(q => q.predicate.value === `${ex}adoptMotion`);
-      for (const adoption of adoptions) {
-        const motion = adoption.subject;
-        const votes = store.getQuads(motion, namedNode(`${ex}votedBy`), null, null);
-        console.log(`🔎 Hook check: ${motion.value} has ${votes.length} votes in store.`);
-        if (votes.length === 0) return false;
-      }
-      return true;
-    },
-    effect: 'veto',
-  });
-
-  tx.addHook({
-    id: 'audit-log',
-    mode: 'post',
-    condition: async () => true,
-    effect: async (_store, delta) => {
-      delta.additions.forEach(q => {
-        console.log(`🪵 Audit: ${q.subject.value} ${q.predicate.value} ${q.object.value}`);
-      });
-    },
-  });
-
-  // === Helper to apply commits ===
-  async function commit(description, additions, actor) {
-    console.log(`\n🤖 ${description}`);
-    const delta = { additions, removals: [] };
-    const { receipt, store: updatedStore } = await tx.apply(store, delta, {
-      actor,
-    });
-
-    // Dump motion state after each commit
-    const motion1Quads = updatedStore.getQuads(namedNode(`${ex}motion1`), null, null, null);
-    console.log('📊 Current motion1 state:');
-    motion1Quads.forEach(q =>
-      console.log(`   • ${q.subject.value} ${q.predicate.value} ${q.object.value}`)
-    );
-
-    // Use the new printReceipt helper
-    printReceipt(receipt, { verbose: true });
-  }
-
-  // === Scenario ===
-  await commit(
-    'PlannerAgent proposes: Introduce motion1: fund AI project',
-    [quad(namedNode(`${ex}motion1`), namedNode(`${ex}introducedBy`), literal('PlannerAgent'))],
-    'PlannerAgent'
-  );
-
-  await commit(
-    'ResearchAgent proposes: Second motion1',
-    [quad(namedNode(`${ex}motion1`), namedNode(`${ex}secondedBy`), literal('ResearchAgent'))],
-    'ResearchAgent'
-  );
-
-  await commit(
-    'CoderAgent proposes: Vote YES on motion1',
-    [quad(namedNode(`${ex}motion1`), namedNode(`${ex}votedBy`), literal('CoderAgent'))],
-    'CoderAgent'
-  );
-
-  await commit(
-    'PlannerAgent proposes: Adopt motion1',
-    [quad(namedNode(`${ex}motion1`), namedNode(`${ex}adoptMotion`), literal('PlannerAgent'))],
-    'PlannerAgent'
-  );
-
-  await commit(
-    'AdversarialAgent proposes: Adopt motion2 (no process)',
-    [quad(namedNode(`${ex}motion2`), namedNode(`${ex}adoptMotion`), literal('AdversarialAgent'))],
-    'AdversarialAgent'
-  );
-
-  console.log('\n✅ Debug demo complete.');
-}
-
-main().catch(err => {
-  console.error('❌ Demo failed:', err);
-  process.exit(1);
-});

package/src/ken.mjs

@@ -1,149 +0,0 @@
-/**
- * @file Knowledge Engine Bulk Example with Assertions
- */
-
-import {
-  _parseTurtle,
-  _toTurtle,
-  query,
-  validateShacl,
-  reason,
-  canonicalize,
-  isIsomorphic,
-  TransactionManager,
-} from './knowledge-engine.mjs';
-
-import { UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
-import { createStore } from '@unrdf/oxigraph'; // TODO: Replace with Oxigraph Store
-import { faker } from '@faker-js/faker';
-import assert from 'assert';
-
-const { namedNode, literal, quad } = DataFactory;
-
-async function generatePeople(count) {
-  const store = createStore();
-  const ex = 'http://example.org/';
-
-  for (let i = 0; i < count; i++) {
-    const id = faker.string.uuid();
-    const iri = namedNode(`${ex}person-${id}`);
-    const name = literal(faker.person.firstName());
-    const age = literal(
-      faker.number.int({ min: 18, max: 90 }).toString(),
-      namedNode('http://www.w3.org/2001/XMLSchema#integer')
-    );
-
-    store.addQuad(iri, namedNode(`${ex}type`), namedNode(`${ex}Person`));
-    store.addQuad(iri, namedNode(`${ex}name`), name);
-    store.addQuad(iri, namedNode(`${ex}age`), age);
-
-    if (i > 0 && Math.random() > 0.5) {
-      const otherIndex = Math.floor(Math.random() * i);
-      const otherIri = namedNode(`${ex}person-${otherIndex}`);
-      store.addQuad(iri, namedNode(`${ex}knows`), otherIri);
-    }
-  }
-
-  return store;
-}
-
-async function main() {
-  const bulkStore = await generatePeople(50);
-  console.log('Generated bulk store size:', bulkStore.size);
-
-  // === Assertion 1: Store has expected number of quads ===
-  assert(bulkStore.size >= 150, 'Store should have at least 3 triples per person');
-
-  // === SPARQL Query ===
-  const rows = await query(
-    bulkStore,
-    `
-    PREFIX ex: <http://example.org/>
-    SELECT ?person ?name ?age WHERE {
-      ?person ex:name ?name ;
-              ex:age ?age .
-    } LIMIT 5
-  `
-  );
-  console.log('SPARQL query results:', rows);
-  assert(rows.length > 0, 'SPARQL query should return at least 1 result');
-  rows.forEach(r => {
-    console.log('Row:', r);
-    assert(r.name && r.name !== '[object Object]', 'Each row should have a name');
-    assert(r.age && r.age !== '[object Object]', 'Each row should have an age');
-  });
-
-  // === SHACL Validation ===
-  const shapesTtl = `
-    @prefix sh: <http://www.w3.org/ns/shacl#> .
-    @prefix ex: <http://example.org/> .
-    @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-
-    ex:PersonShape a sh:NodeShape ;
-      sh:targetClass ex:Person ;
-      sh:property [
-        sh:path ex:name ;
-        sh:datatype xsd:string ;
-        sh:minCount 1
-      ] ;
-      sh:property [
-        sh:path ex:age ;
-        sh:datatype xsd:integer ;
-        sh:minInclusive 0
-      ] .
-  `;
-  const report = validateShacl(bulkStore, shapesTtl);
-  console.log('SHACL validation report:', report);
-  // SHACL validation may return undefined for conforms, so we check that there are no results
-  assert(report.conforms !== false, 'SHACL validation should not have violations');
-  assert(report.results.length === 0, 'SHACL validation should have no validation results');
-
-  // === Reasoning ===
-  const rulesTtl = `
-    @prefix ex: <http://example.org/> .
-    { ?x ex:knows ?y } => { ?y ex:knows ?x } .
-  `;
-  const reasonedStore = await reason(bulkStore, rulesTtl);
-  assert(reasonedStore.size >= bulkStore.size, 'Reasoned store should be same size or larger');
-
-  // === Canonicalization & Isomorphism ===
-  const canonical = await canonicalize(bulkStore);
-  assert(canonical.length > 0, 'Canonicalization should produce non-empty output');
-
-  const copy = createStore(bulkStore.getQuads());
-  const iso = await isIsomorphic(bulkStore, copy);
-  assert.strictEqual(iso, true, 'Copy of store should be isomorphic');
-
-  // === Transactions ===
-  const tx = new TransactionManager();
-  tx.addHook({
-    id: 'no-teenagers',
-    mode: 'pre',
-    condition: async (_store, delta) => {
-      return !delta.additions.some(
-        q => q.predicate.value.endsWith('age') && parseInt(q.object.value) < 18
-      );
-    },
-    effect: 'veto',
-  });
-
-  const delta = {
-    additions: [
-      quad(
-        namedNode('http://example.org/person-extra'),
-        namedNode('http://example.org/age'),
-        literal('15')
-      ),
-    ],
-    removals: [],
-  };
-  const { receipt } = await tx.apply(bulkStore, delta);
-  assert.strictEqual(receipt.committed, false, 'Transaction with underage person should be vetoed');
-
-  console.log('✅ All assertions passed successfully.');
-}
-
-main().catch(err => {
-  console.error('❌ Assertion failed:', err.message);
-  process.exit(1);
-});

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

@@ -1,190 +0,0 @@
-/**
- * @file Built-in RDFS Inference Rules
- * @module @unrdf/knowledge-engine/builtin-rules
- */
-
-import { defineRule } from './rules.mjs';
-
-/**
- * RDFS SubClass inference rule
- * If A rdfs:subClassOf B and X rdf:type A, then infer X rdf:type B
- */
-export const rdfsSubClassRule = defineRule({
-  name: 'rdfs:subClassOf',
-  description: 'Infer type from subclass hierarchy',
-  pattern: [
-    { subject: '?subClass', predicate: 'rdfs:subClassOf', object: '?superClass' },
-    { subject: '?instance', predicate: 'rdf:type', object: '?subClass' },
-  ],
-  consequent: {
-    subject: '?instance',
-    predicate: 'rdf:type',
-    object: '?superClass',
-  },
-  salience: 80,
-});
-
-/**
- * RDFS SubProperty inference rule
- * If P rdfs:subPropertyOf Q and X P Y, then infer X Q Y
- */
-export const rdfsSubPropertyRule = defineRule({
-  name: 'rdfs:subPropertyOf',
-  description: 'Infer property from subproperty hierarchy',
-  pattern: [
-    { subject: '?subProp', predicate: 'rdfs:subPropertyOf', object: '?superProp' },
-    { subject: '?x', predicate: '?subProp', object: '?y' },
-  ],
-  consequent: {
-    subject: '?x',
-    predicate: '?superProp',
-    object: '?y',
-  },
-  salience: 75,
-});
-
-/**
- * RDFS Domain inference rule
- * If P rdfs:domain C and X P Y, then infer X rdf:type C
- */
-export const rdfsDomainRule = defineRule({
-  name: 'rdfs:domain',
-  description: 'Infer type from property domain',
-  pattern: [
-    { subject: '?property', predicate: 'rdfs:domain', object: '?class' },
-    { subject: '?x', predicate: '?property', object: '?y' },
-  ],
-  consequent: {
-    subject: '?x',
-    predicate: 'rdf:type',
-    object: '?class',
-  },
-  salience: 70,
-});
-
-/**
- * RDFS Range inference rule
- * If P rdfs:range C and X P Y, then infer Y rdf:type C
- */
-export const rdfsRangeRule = defineRule({
-  name: 'rdfs:range',
-  description: 'Infer type from property range',
-  pattern: [
-    { subject: '?property', predicate: 'rdfs:range', object: '?class' },
-    { subject: '?x', predicate: '?property', object: '?y' },
-  ],
-  consequent: {
-    subject: '?y',
-    predicate: 'rdf:type',
-    object: '?class',
-  },
-  salience: 70,
-});
-
-/**
- * OWL Transitive Property rule
- * If P rdf:type owl:TransitiveProperty and X P Y and Y P Z, then infer X P Z
- */
-export const owlTransitiveRule = defineRule({
-  name: 'owl:TransitiveProperty',
-  description: 'Apply transitive property closure',
-  pattern: [
-    { subject: '?property', predicate: 'rdf:type', object: 'owl:TransitiveProperty' },
-    { subject: '?x', predicate: '?property', object: '?y' },
-    { subject: '?y', predicate: '?property', object: '?z' },
-  ],
-  consequent: {
-    subject: '?x',
-    predicate: '?property',
-    object: '?z',
-  },
-  salience: 60,
-});
-
-/**
- * OWL Symmetric Property rule
- * If P rdf:type owl:SymmetricProperty and X P Y, then infer Y P X
- */
-export const owlSymmetricRule = defineRule({
-  name: 'owl:SymmetricProperty',
-  description: 'Apply symmetric property',
-  pattern: [
-    { subject: '?property', predicate: 'rdf:type', object: 'owl:SymmetricProperty' },
-    { subject: '?x', predicate: '?property', object: '?y' },
-  ],
-  consequent: {
-    subject: '?y',
-    predicate: '?property',
-    object: '?x',
-  },
-  salience: 65,
-});
-
-/**
- * OWL Inverse Property rule
- * If P owl:inverseOf Q and X P Y, then infer Y Q X
- */
-export const owlInverseRule = defineRule({
-  name: 'owl:inverseOf',
-  description: 'Apply inverse property',
-  pattern: [
-    { subject: '?p', predicate: 'owl:inverseOf', object: '?q' },
-    { subject: '?x', predicate: '?p', object: '?y' },
-  ],
-  consequent: {
-    subject: '?y',
-    predicate: '?q',
-    object: '?x',
-  },
-  salience: 65,
-});
-
-/**
- * Collection of all built-in RDFS/OWL rules
- */
-export const builtinRules = [
-  rdfsSubClassRule,
-  rdfsSubPropertyRule,
-  rdfsDomainRule,
-  rdfsRangeRule,
-  owlTransitiveRule,
-  owlSymmetricRule,
-  owlInverseRule,
-];
-
-/**
- * Get all built-in rules
- *
- * @returns {Object[]} Array of built-in rules
- *
- * @example
- * const rules = getBuiltinRules();
- * addRules(engine, rules);
- */
-export function getBuiltinRules() {
-  return builtinRules;
-}
-
-/**
- * Get RDFS rules only (no OWL)
- *
- * @returns {Object[]} Array of RDFS rules
- *
- * @example
- * const rdfsRules = getRDFSRules();
- */
-export function getRDFSRules() {
-  return [rdfsSubClassRule, rdfsSubPropertyRule, rdfsDomainRule, rdfsRangeRule];
-}
-
-/**
- * Get OWL rules only
- *
- * @returns {Object[]} Array of OWL rules
- *
- * @example
- * const owlRules = getOWLRules();
- */
-export function getOWLRules() {
-  return [owlTransitiveRule, owlSymmetricRule, owlInverseRule];
-}