rust-kgdb 0.4.1 → 0.4.2

package/examples/datalog-example.ts

@@ -0,0 +1,478 @@
+/**
+ * Datalog Example for rust-kgdb TypeScript SDK
+ *
+ * Demonstrates Datalog reasoning capabilities including:
+ * - Adding facts and rules
+ * - Semi-naive evaluation
+ * - Recursive rule evaluation
+ * - Stratified negation
+ * - Query evaluation
+ * - Integration with RDF graphs
+ */
+
+import { DatalogEngine, GraphDb } from 'rust-kgdb';
+
+// =============================================================================
+// Example 1: Basic Facts and Rules
+// =============================================================================
+
+async function basicDatalogExample() {
+    console.log('=== Basic Datalog Facts and Rules ===\n');
+
+    const engine = new DatalogEngine();
+
+    // Add facts: parent(X, Y) means X is parent of Y
+    engine.addFact('parent', ['alice', 'bob']);
+    engine.addFact('parent', ['alice', 'carol']);
+    engine.addFact('parent', ['bob', 'david']);
+    engine.addFact('parent', ['bob', 'eve']);
+    engine.addFact('parent', ['carol', 'frank']);
+
+    console.log('Facts added:');
+    console.log('  parent(alice, bob)');
+    console.log('  parent(alice, carol)');
+    console.log('  parent(bob, david)');
+    console.log('  parent(bob, eve)');
+    console.log('  parent(carol, frank)\n');
+
+    // Add rule: grandparent(X, Z) :- parent(X, Y), parent(Y, Z)
+    engine.addRule(
+        'grandparent',          // head predicate
+        ['X', 'Z'],             // head variables
+        [
+            { predicate: 'parent', args: ['X', 'Y'] },
+            { predicate: 'parent', args: ['Y', 'Z'] }
+        ]
+    );
+
+    console.log('Rule added:');
+    console.log('  grandparent(X, Z) :- parent(X, Y), parent(Y, Z)\n');
+
+    // Evaluate to derive all facts
+    engine.evaluate();
+
+    // Query grandparents
+    const grandparents = engine.query('grandparent', ['?who', '?grandchild']);
+    console.log('Query: grandparent(?who, ?grandchild)');
+    console.log('Results:');
+    for (const result of grandparents) {
+        console.log(`  ${result.who} is grandparent of ${result.grandchild}`);
+    }
+    console.log();
+}
+
+// =============================================================================
+// Example 2: Recursive Rules (Transitive Closure)
+// =============================================================================
+
+async function recursiveDatalogExample() {
+    console.log('=== Recursive Rules (Transitive Closure) ===\n');
+
+    const engine = new DatalogEngine();
+
+    // Add edge facts for a graph
+    engine.addFact('edge', ['a', 'b']);
+    engine.addFact('edge', ['b', 'c']);
+    engine.addFact('edge', ['c', 'd']);
+    engine.addFact('edge', ['d', 'e']);
+    engine.addFact('edge', ['a', 'c']); // shortcut
+
+    console.log('Graph edges: a->b, b->c, c->d, d->e, a->c\n');
+
+    // Base case: path(X, Y) :- edge(X, Y)
+    engine.addRule(
+        'path',
+        ['X', 'Y'],
+        [{ predicate: 'edge', args: ['X', 'Y'] }]
+    );
+
+    // Recursive case: path(X, Z) :- edge(X, Y), path(Y, Z)
+    engine.addRule(
+        'path',
+        ['X', 'Z'],
+        [
+            { predicate: 'edge', args: ['X', 'Y'] },
+            { predicate: 'path', args: ['Y', 'Z'] }
+        ]
+    );
+
+    console.log('Rules added:');
+    console.log('  path(X, Y) :- edge(X, Y)         % base case');
+    console.log('  path(X, Z) :- edge(X, Y), path(Y, Z)  % recursive case\n');
+
+    // Evaluate using semi-naive algorithm
+    const iterations = engine.evaluateSemiNaive();
+    console.log(`Semi-naive evaluation completed in ${iterations} iterations\n`);
+
+    // Query all paths from 'a'
+    const paths = engine.query('path', ['a', '?end']);
+    console.log('Query: path(a, ?end)');
+    console.log('Results (nodes reachable from a):');
+    for (const result of paths) {
+        console.log(`  a can reach ${result.end}`);
+    }
+    console.log();
+}
+
+// =============================================================================
+// Example 3: Stratified Negation
+// =============================================================================
+
+async function negationDatalogExample() {
+    console.log('=== Stratified Negation ===\n');
+
+    const engine = new DatalogEngine();
+
+    // Add employee facts
+    engine.addFact('employee', ['alice', 'engineering']);
+    engine.addFact('employee', ['bob', 'engineering']);
+    engine.addFact('employee', ['carol', 'sales']);
+    engine.addFact('employee', ['david', 'hr']);
+
+    // Add manager facts
+    engine.addFact('manager', ['alice']);
+    engine.addFact('manager', ['carol']);
+
+    console.log('Facts:');
+    console.log('  employee(alice, engineering), employee(bob, engineering)');
+    console.log('  employee(carol, sales), employee(david, hr)');
+    console.log('  manager(alice), manager(carol)\n');
+
+    // Rule: non_manager(X) :- employee(X, _), NOT manager(X)
+    engine.addRuleWithNegation(
+        'non_manager',
+        ['X'],
+        [{ predicate: 'employee', args: ['X', '_'] }],
+        [{ predicate: 'manager', args: ['X'] }]  // negated atoms
+    );
+
+    console.log('Rule with negation:');
+    console.log('  non_manager(X) :- employee(X, _), NOT manager(X)\n');
+
+    // Stratified evaluation (handles negation correctly)
+    engine.evaluateStratified();
+
+    // Query non-managers
+    const nonManagers = engine.query('non_manager', ['?person']);
+    console.log('Query: non_manager(?person)');
+    console.log('Results:');
+    for (const result of nonManagers) {
+        console.log(`  ${result.person} is not a manager`);
+    }
+    console.log();
+}
+
+// =============================================================================
+// Example 4: Aggregate Functions
+// =============================================================================
+
+async function aggregateDatalogExample() {
+    console.log('=== Aggregate Functions ===\n');
+
+    const engine = new DatalogEngine();
+
+    // Add sales facts: sale(product, amount, region)
+    engine.addFact('sale', ['laptop', '1200', 'west']);
+    engine.addFact('sale', ['laptop', '1100', 'east']);
+    engine.addFact('sale', ['phone', '800', 'west']);
+    engine.addFact('sale', ['phone', '850', 'east']);
+    engine.addFact('sale', ['tablet', '500', 'west']);
+    engine.addFact('sale', ['tablet', '450', 'east']);
+
+    console.log('Sales facts added\n');
+
+    // Rule with aggregation: total_by_product(P, sum(A)) :- sale(P, A, _)
+    engine.addAggregateRule(
+        'total_by_product',
+        ['Product', 'Total'],
+        { predicate: 'sale', args: ['Product', 'Amount', '_'] },
+        { function: 'sum', variable: 'Amount', output: 'Total' },
+        ['Product']  // group by
+    );
+
+    // Rule: avg_by_region(R, avg(A)) :- sale(_, A, R)
+    engine.addAggregateRule(
+        'avg_by_region',
+        ['Region', 'Average'],
+        { predicate: 'sale', args: ['_', 'Amount', 'Region'] },
+        { function: 'avg', variable: 'Amount', output: 'Average' },
+        ['Region']
+    );
+
+    console.log('Aggregate rules added:');
+    console.log('  total_by_product(P, sum(A)) :- sale(P, A, _)');
+    console.log('  avg_by_region(R, avg(A)) :- sale(_, A, R)\n');
+
+    engine.evaluate();
+
+    // Query totals by product
+    const totals = engine.query('total_by_product', ['?product', '?total']);
+    console.log('Total sales by product:');
+    for (const result of totals) {
+        console.log(`  ${result.product}: $${result.total}`);
+    }
+
+    // Query averages by region
+    const avgs = engine.query('avg_by_region', ['?region', '?avg']);
+    console.log('\nAverage sale by region:');
+    for (const result of avgs) {
+        console.log(`  ${result.region}: $${result.avg}`);
+    }
+    console.log();
+}
+
+// =============================================================================
+// Example 5: RDF Graph Integration
+// =============================================================================
+
+async function rdfIntegrationExample() {
+    console.log('=== RDF Graph Integration ===\n');
+
+    // Create RDF graph
+    const db = new GraphDb('http://example.org/company');
+
+    // Load company data
+    const ttl = `
+        @prefix ex: <http://example.org/> .
+        @prefix foaf: <http://xmlns.com/foaf/0.1/> .
+        @prefix org: <http://www.w3.org/ns/org#> .
+
+        ex:alice a foaf:Person ;
+            foaf:name "Alice" ;
+            org:memberOf ex:engineering .
+
+        ex:bob a foaf:Person ;
+            foaf:name "Bob" ;
+            org:memberOf ex:engineering ;
+            org:reportsTo ex:alice .
+
+        ex:carol a foaf:Person ;
+            foaf:name "Carol" ;
+            org:memberOf ex:sales .
+
+        ex:engineering a org:OrganizationalUnit ;
+            org:name "Engineering Department" .
+
+        ex:sales a org:OrganizationalUnit ;
+            org:name "Sales Department" .
+    `;
+
+    db.loadTtl(ttl, null);
+    console.log('RDF graph loaded with company data\n');
+
+    // Create Datalog engine from RDF
+    const engine = db.toDatalog();
+
+    // The RDF triples become facts:
+    // triple(subject, predicate, object)
+    console.log('RDF triples converted to Datalog facts\n');
+
+    // Add reasoning rules
+    // colleague(X, Y) :- memberOf(X, Dept), memberOf(Y, Dept), X != Y
+    engine.addRule(
+        'colleague',
+        ['X', 'Y'],
+        [
+            { predicate: 'triple', args: ['X', 'http://www.w3.org/ns/org#memberOf', 'Dept'] },
+            { predicate: 'triple', args: ['Y', 'http://www.w3.org/ns/org#memberOf', 'Dept'] }
+        ],
+        { filter: 'X != Y' }
+    );
+
+    // manager(X, Y) :- reportsTo(Y, X)
+    engine.addRule(
+        'manager',
+        ['Manager', 'Employee'],
+        [
+            { predicate: 'triple', args: ['Employee', 'http://www.w3.org/ns/org#reportsTo', 'Manager'] }
+        ]
+    );
+
+    console.log('Reasoning rules added:');
+    console.log('  colleague(X, Y) :- memberOf(X, Dept), memberOf(Y, Dept), X != Y');
+    console.log('  manager(M, E) :- reportsTo(E, M)\n');
+
+    engine.evaluate();
+
+    // Query colleagues
+    const colleagues = engine.query('colleague', ['?person1', '?person2']);
+    console.log('Colleagues (same department):');
+    for (const result of colleagues) {
+        console.log(`  ${result.person1.split('/').pop()} and ${result.person2.split('/').pop()}`);
+    }
+
+    // Query managers
+    const managers = engine.query('manager', ['?manager', '?employee']);
+    console.log('\nManagement relationships:');
+    for (const result of managers) {
+        console.log(`  ${result.manager.split('/').pop()} manages ${result.employee.split('/').pop()}`);
+    }
+    console.log();
+}
+
+// =============================================================================
+// Example 6: Access Control Rules (Practical Application)
+// =============================================================================
+
+async function accessControlExample() {
+    console.log('=== Access Control Rules ===\n');
+
+    const engine = new DatalogEngine();
+
+    // User roles
+    engine.addFact('role', ['alice', 'admin']);
+    engine.addFact('role', ['bob', 'developer']);
+    engine.addFact('role', ['carol', 'developer']);
+    engine.addFact('role', ['david', 'viewer']);
+
+    // Resource permissions by role
+    engine.addFact('permission', ['admin', 'read']);
+    engine.addFact('permission', ['admin', 'write']);
+    engine.addFact('permission', ['admin', 'delete']);
+    engine.addFact('permission', ['developer', 'read']);
+    engine.addFact('permission', ['developer', 'write']);
+    engine.addFact('permission', ['viewer', 'read']);
+
+    // Resource ownership
+    engine.addFact('owns', ['alice', 'resource1']);
+    engine.addFact('owns', ['bob', 'resource2']);
+
+    console.log('Access control facts loaded\n');
+
+    // Rule: can_access(User, Resource, Action) :- role(User, Role), permission(Role, Action)
+    engine.addRule(
+        'can_access',
+        ['User', 'Resource', 'Action'],
+        [
+            { predicate: 'role', args: ['User', 'Role'] },
+            { predicate: 'permission', args: ['Role', 'Action'] }
+        ]
+    );
+
+    // Rule: owner_override(User, Resource, delete) :- owns(User, Resource)
+    engine.addRule(
+        'can_access',
+        ['User', 'Resource', 'delete'],
+        [
+            { predicate: 'owns', args: ['User', 'Resource'] }
+        ]
+    );
+
+    console.log('Access control rules:');
+    console.log('  can_access(U, R, A) :- role(U, Role), permission(Role, A)');
+    console.log('  can_access(U, R, delete) :- owns(U, R)  % owner override\n');
+
+    engine.evaluate();
+
+    // Check specific access
+    const checkAccess = (user: string, action: string) => {
+        const results = engine.query('can_access', [user, '?resource', action]);
+        return results.length > 0;
+    };
+
+    const checks = [
+        ['alice', 'delete'],
+        ['bob', 'write'],
+        ['bob', 'delete'],
+        ['david', 'read'],
+        ['david', 'write']
+    ];
+
+    console.log('Access checks:');
+    for (const [user, action] of checks) {
+        const allowed = checkAccess(user, action);
+        const icon = allowed ? '✓' : '✗';
+        console.log(`  ${icon} ${user} can ${action}: ${allowed}`);
+    }
+
+    // Bob can delete resource2 because he owns it
+    const bobCanDelete = engine.query('can_access', ['bob', 'resource2', 'delete']);
+    console.log(`\n  Bob can delete resource2 (owner): ${bobCanDelete.length > 0}`);
+    console.log();
+}
+
+// =============================================================================
+// Example 7: Incremental Updates
+// =============================================================================
+
+async function incrementalExample() {
+    console.log('=== Incremental Updates ===\n');
+
+    const engine = new DatalogEngine();
+
+    // Initial facts
+    engine.addFact('friend', ['alice', 'bob']);
+    engine.addFact('friend', ['bob', 'carol']);
+
+    // Bidirectional friendship rule
+    engine.addRule(
+        'friends_with',
+        ['X', 'Y'],
+        [{ predicate: 'friend', args: ['X', 'Y'] }]
+    );
+    engine.addRule(
+        'friends_with',
+        ['X', 'Y'],
+        [{ predicate: 'friend', args: ['Y', 'X'] }]
+    );
+
+    // Transitive friends-of-friends
+    engine.addRule(
+        'fof',
+        ['X', 'Z'],
+        [
+            { predicate: 'friends_with', args: ['X', 'Y'] },
+            { predicate: 'friends_with', args: ['Y', 'Z'] }
+        ],
+        { filter: 'X != Z' }
+    );
+
+    engine.evaluate();
+
+    console.log('Initial state:');
+    let fofs = engine.query('fof', ['alice', '?friend']);
+    console.log(`  Alice's friends-of-friends: ${fofs.map(r => r.friend).join(', ')}\n`);
+
+    // Incremental update: add new friendship
+    console.log('Adding new fact: friend(carol, david)');
+    engine.addFact('friend', ['carol', 'david']);
+
+    // Incremental evaluation (only processes new facts)
+    engine.evaluateIncremental();
+
+    console.log('\nAfter incremental update:');
+    fofs = engine.query('fof', ['alice', '?friend']);
+    console.log(`  Alice's friends-of-friends: ${fofs.map(r => r.friend).join(', ')}`);
+
+    console.log('\nIncremental evaluation is much faster for dynamic graphs!');
+    console.log();
+}
+
+// =============================================================================
+// Run All Examples
+// =============================================================================
+
+async function main() {
+    console.log('========================================');
+    console.log('   Datalog Reasoning Examples');
+    console.log('========================================\n');
+
+    try {
+        await basicDatalogExample();
+        await recursiveDatalogExample();
+        await negationDatalogExample();
+        await aggregateDatalogExample();
+        await rdfIntegrationExample();
+        await accessControlExample();
+        await incrementalExample();
+
+        console.log('========================================');
+        console.log('   All examples completed successfully!');
+        console.log('========================================');
+    } catch (error) {
+        console.error('Error running examples:', error);
+        process.exit(1);
+    }
+}
+
+main();