@unrdf/knowledge-engine 5.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @unrdf/knowledge-engine
+
+![Version](https://img.shields.io/badge/version-5.0.0--beta.1-blue) ![Production Ready](https://img.shields.io/badge/production-ready-green)
+
+
+**Rule Engine, Inference, and Pattern Matching** *(Optional Extension)*
+
+Apply business rules and inference to RDF data. Includes reasoning engine and pattern matching.
+
+## Installation
+
+```bash
+pnpm add @unrdf/knowledge-engine
+```
+
+## 📚 Examples
+
+See these examples that demonstrate @unrdf/knowledge-engine:
+
+- **[knowledge-engine-example.mjs](../../examples/knowledge-engine-example.mjs)** - Complete AI semantic analysis demo (1 hour)
+- **[ai-semantic-example.mjs](../../examples/ai-semantic-example.mjs)** - Embedding-based semantic search
+- **[comprehensive-feature-test.mjs](../../examples/comprehensive-feature-test.mjs)** - Knowledge engine integration
+
+**Want AI-powered queries?** Start with [knowledge-engine-example.mjs](../../examples/knowledge-engine-example.mjs).
+
+## Quick Start
+
+```javascript
+import { inferPatterns, createRuleSet } from '@unrdf/knowledge-engine'
+
+// Define rules
+const rules = createRuleSet([
+  {
+    name: 'infer-person',
+    pattern: '?x rdf:type foaf:Person',
+    then: '?x rdfs:label ?name'
+  }
+])
+
+// Apply inference
+const inferred = await inferPatterns(store, rules)
+```
+
+## Features
+
+- ✅ Forward chaining inference
+- ✅ Rule definition and execution
+- ✅ Pattern matching on RDF data
+- ✅ Built-in ontology reasoning (RDF, RDFS, OWL)
+- ✅ Custom rule sets
+- ✅ Performance optimization
+
+## Use Cases
+
+- **Business rules**: Apply domain rules to RDF
+- **Data enrichment**: Infer new facts from existing data
+- **Ontology reasoning**: RDFS and OWL inference
+- **Data quality**: Detect and fix inconsistencies
+- **Knowledge extraction**: Mine patterns from data
+
+## Documentation
+
+- **[API Reference](./docs/API.md)** - Complete API documentation
+- **[User Guide](./docs/GUIDE.md)** - Rule definition and usage
+- **[Examples](./examples/)** - Code examples
+- **[Contributing](./docs/CONTRIBUTING.md)** - How to contribute
+
+## Status
+
+**Optional Extension** - Not required for core UNRDF functionality.
+Use only if you need rule-based inference.
+
+## Depends On
+
+- `@unrdf/core` - RDF substrate
+- `@unrdf/streaming` - Change subscriptions
+
+## VOC Usage
+
+- VOC-3: ML Agent (pattern matching)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@unrdf/knowledge-engine",
+  "version": "5.0.1",
+  "description": "UNRDF Knowledge Engine - Rule Engine, Inference, and Pattern Matching (Optional Extension)",
+  "type": "module",
+  "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./query": "./src/query.mjs",
+    "./canonicalize": "./src/canonicalize.mjs",
+    "./parse": "./src/parse.mjs"
+  },
+  "sideEffects": false,
+  "files": [
+    "src/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "rdf",
+    "knowledge-engine",
+    "inference",
+    "reasoning",
+    "rules"
+  ],
+  "dependencies": {
+    "eyereasoner": "^18.23.0",
+    "@unrdf/core": "5.0.1",
+    "@unrdf/streaming": "5.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "vitest": "^4.0.15"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unrdf/unrdf.git",
+    "directory": "packages/knowledge-engine"
+  },
+  "bugs": {
+    "url": "https://github.com/unrdf/unrdf/issues"
+  },
+  "homepage": "https://github.com/unrdf/unrdf#readme",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run --coverage",
+    "test:fast": "vitest run --coverage",
+    "test:watch": "vitest --coverage",
+    "build": "node build.config.mjs",
+    "lint": "eslint src/ test/ --max-warnings=0",
+    "lint:fix": "eslint src/ test/ --fix",
+    "format": "prettier --write src/ test/",
+    "format:check": "prettier --check src/ test/",
+    "clean": "rm -rf dist/ .nyc_output/ coverage/",
+    "dev": "echo 'Development mode for @unrdf/knowledge-engine'"
+  }
+}

package/src/browser-shims.mjs

@@ -0,0 +1,343 @@
+/**
+ * @file Browser compatibility shims for Node.js APIs
+ * @module browser-shims
+ *
+ * @description
+ * Provides browser-compatible polyfills for Node.js APIs used in the knowledge engine.
+ * This allows the same codebase to work in both Node.js and browser environments.
+ */
+
+/**
+ * Check if we're running in a browser environment
+ */
+export const isBrowser =
+  typeof globalThis?.window !== 'undefined' && typeof globalThis?.window?.document !== 'undefined';
+
+/**
+ * Check if we're running in Node.js environment
+ */
+export const isNode = (() => {
+  try {
+    return typeof process !== 'undefined' && !!process?.versions?.node;
+  } catch {
+    return false;
+  }
+})();
+
+// Random UUID generation - use crypto.randomUUID if available, otherwise fallback
+/**
+ *
+ */
+export function randomUUID() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+
+  // Fallback UUID generation
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+// Path utilities - browser-compatible version
+export const path = {
+  join: (...args) => args.filter(Boolean).join('/').replace(/\/+/g, '/'),
+  resolve: (...args) => args.filter(Boolean).join('/').replace(/\/+/g, '/'),
+  dirname: path => path.replace(/\/$/, '').split('/').slice(0, -1).join('/') || '.',
+  basename: path => path.split('/').pop() || '',
+  extname: path => {
+    const ext = path.split('.').pop();
+    return ext && ext !== path ? '.' + ext : '';
+  },
+};
+
+// Process utilities
+export const process = {
+  cwd: () => '/',
+  env: isBrowser
+    ? {}
+    : (() => {
+        try {
+          return process.env;
+        } catch {
+          return {};
+        }
+      })(),
+  versions: isBrowser
+    ? {}
+    : (() => {
+        try {
+          return process.versions;
+        } catch {
+          return {};
+        }
+      })(),
+};
+
+// File system operations - browser-compatible (no-ops or memory-based)
+class BrowserFileSystem {
+  #files = new Map();
+  #directories = new Set(['/']);
+
+  constructor() {
+    // Create some default directories
+    this.#directories.add('/src');
+    this.#directories.add('/dist');
+    this.#directories.add('/examples');
+  }
+
+  clear() {
+    this.#files.clear();
+    this.#directories.clear();
+    this.#directories.add('/');
+    this.#directories.add('/src');
+    this.#directories.add('/dist');
+    this.#directories.add('/examples');
+  }
+
+  existsSync(path) {
+    return this.#files.has(path) || this.#directories.has(path);
+  }
+
+  readFileSync(path, encoding = 'utf8') {
+    const content = this.#files.get(path);
+    if (!content) {
+      throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    }
+    return encoding === 'utf8' ? content : Buffer.from(content, 'utf8');
+  }
+
+  writeFileSync(path, data, encoding = 'utf8') {
+    const content = encoding === 'utf8' ? data : data.toString();
+    this.#files.set(path, content);
+
+    // Ensure parent directories exist
+    const parent = path.dirname(path);
+    if (!this.#directories.has(parent) && parent !== path) {
+      this.#directories.add(parent);
+    }
+  }
+
+  mkdirSync(path, _options = {}) {
+    if (this.#directories.has(path)) {
+      throw new Error(`EEXIST: file already exists, mkdir '${path}'`);
+    }
+    this.#directories.add(path);
+  }
+
+  readdirSync(path) {
+    return Array.from(this.#files.keys()).filter(file => file.startsWith(path + '/'));
+  }
+
+  // Async versions
+  async readFile(path, encoding = 'utf8') {
+    return Promise.resolve(this.readFileSync(path, encoding));
+  }
+
+  async writeFile(path, data, encoding = 'utf8') {
+    this.writeFileSync(path, data, encoding);
+    return Promise.resolve();
+  }
+
+  async mkdir(path, options = {}) {
+    this.mkdirSync(path, options);
+    return Promise.resolve();
+  }
+}
+
+export const fs = isBrowser
+  ? new BrowserFileSystem()
+  : await import('node:fs').then(m => m.default);
+export const fsPromises = isBrowser
+  ? new BrowserFileSystem()
+  : await import('node:fs/promises').then(m => m.default);
+
+// Worker thread polyfill for browser
+/**
+ *
+ */
+export class BrowserWorker {
+  /**
+   *
+   */
+  constructor(source, options = {}) {
+    if (typeof source === 'string' && isBrowser) {
+      // Convert string to blob URL (browser only)
+      const blob = new Blob([source], { type: 'application/javascript' });
+      this.worker = new Worker(URL.createObjectURL(blob), options);
+    } else if (typeof source === 'string' && isNode) {
+      // In Node.js, can't create Worker from inline code - need a file
+      // Create a mock worker for testing purposes
+      this.worker = null;
+      this.mockMode = true;
+    } else {
+      // Assume it's a file path
+      this.worker = new Worker(source, options);
+    }
+
+    this.messageHandlers = [];
+    this.errorHandlers = [];
+    this.exitHandlers = [];
+    this.terminated = false;
+
+    if (this.worker) {
+      this.worker.onmessage = event => {
+        this.messageHandlers.forEach(handler => handler(event.data));
+      };
+
+      this.worker.onerror = error => {
+        this.errorHandlers.forEach(handler => handler(error));
+      };
+    }
+  }
+
+  /**
+   *
+   */
+  postMessage(data) {
+    if (this.terminated) return;
+    if (this.worker) {
+      this.worker.postMessage(data);
+    }
+  }
+
+  /**
+   *
+   */
+  terminate() {
+    this.terminated = true;
+    if (this.worker) {
+      this.worker.terminate();
+    }
+  }
+
+  /**
+   *
+   */
+  on(event, handler) {
+    switch (event) {
+      case 'message':
+        this.messageHandlers.push(handler);
+        break;
+      case 'error':
+        this.errorHandlers.push(handler);
+        break;
+      case 'exit':
+        this.exitHandlers.push(handler);
+        break;
+    }
+  }
+
+  /**
+   *
+   */
+  once(event, handler) {
+    const wrappedHandler = data => {
+      handler(data);
+      this.removeListener(event, wrappedHandler);
+    };
+    this.on(event, wrappedHandler);
+  }
+
+  /**
+   *
+   */
+  removeListener(event, handler) {
+    switch (event) {
+      case 'message':
+        this.messageHandlers = this.messageHandlers.filter(h => h !== handler);
+        break;
+      case 'error':
+        this.errorHandlers = this.errorHandlers.filter(h => h !== handler);
+        break;
+      case 'exit':
+        this.exitHandlers = this.exitHandlers.filter(h => h !== handler);
+        break;
+    }
+  }
+}
+
+export const Worker = isBrowser
+  ? BrowserWorker
+  : await import('node:worker_threads').then(m => m.Worker);
+
+// Mock child_process.execSync - browser-compatible
+/**
+ *
+ */
+export async function execSync(command, options = {}) {
+  if (isBrowser) {
+    console.warn(`[Browser] execSync not available in browser: ${command}`);
+    return ''; // Return empty string as mock
+  }
+
+  const { execSync: nodeExecSync } = await import('child_process');
+  const result = nodeExecSync(command, { encoding: 'utf8', ...options });
+  // Ensure we return a string, not a Buffer
+  return typeof result === 'string' ? result : result.toString('utf8');
+}
+
+// Hash utilities - use Web Crypto API in browser
+/**
+ *
+ */
+export class BrowserHash {
+  /**
+   *
+   */
+  constructor(algorithm = 'SHA-256') {
+    this.algorithm = algorithm.toLowerCase().replace(/[^a-z0-9]/g, '');
+  }
+
+  /**
+   *
+   */
+  update(data) {
+    this.data = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+    return this;
+  }
+
+  /**
+   *
+   */
+  async digest(encoding = 'hex') {
+    const hashBuffer = await crypto.subtle.digest(this.algorithm, this.data);
+    const hashArray = new Uint8Array(hashBuffer);
+
+    if (encoding === 'hex') {
+      return Array.from(hashArray)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+    }
+
+    return hashArray;
+  }
+}
+
+/**
+ *
+ */
+export async function createHash(algorithm) {
+  if (isBrowser) {
+    return new BrowserHash(algorithm);
+  }
+
+  const { createHash: nodeCreateHash } = await import('node:crypto');
+  return nodeCreateHash(algorithm);
+}
+
+// Export all shims as a unified object
+export default {
+  isBrowser,
+  isNode,
+  randomUUID,
+  path,
+  process,
+  fs,
+  fsPromises,
+  Worker: BrowserWorker,
+  execSync,
+  createHash,
+};