rust-kgdb 0.4.1 → 0.4.3

package/examples/core-concepts-demo.ts

@@ -0,0 +1,502 @@
+#!/usr/bin/env npx ts-node
+/**
+ * Core Concepts Demo - rust-kgdb TypeScript SDK
+ *
+ * This demo walks through ALL core concepts from data ingestion to AI agent execution:
+ *
+ * 1. DATA MODEL: RDF triples, quads, and hypergraphs
+ * 2. DATA INGESTION (Step 0): Loading data with trigger-based embedding generation
+ * 3. SPARQL QUERIES: Declarative graph querying
+ * 4. DATALOG REASONING: Recursive rule evaluation
+ * 5. EMBEDDINGS: Similarity search with HNSW
+ * 6. GRAPHFRAMES: Graph algorithms (PageRank, connected components)
+ * 7. CONCEPT LOOKUP: How agents find schema types (Cmd+/ analogy)
+ * 8. HYPERMIND AGENTS: Natural language to SPARQL execution
+ *
+ * See docs/CORE_CONCEPTS.md for detailed explanations of each concept.
+ */
+
+import {
+    GraphDB,
+    DatalogEngine,
+    EmbeddingService,
+    GraphFrame,
+} from 'rust-kgdb';
+
+// =============================================================================
+// 1. DATA MODEL: RDF Triples and Named Graphs
+// =============================================================================
+
+function demoDataModel(): any {
+    console.log('='.repeat(70));
+    console.log('  1. DATA MODEL: RDF Triples and Named Graphs');
+    console.log('='.repeat(70));
+    console.log();
+
+    // Create a knowledge graph database
+    const db = new GraphDB('http://example.org/company');
+
+    // Load RDF data in Turtle format
+    // Each statement is a TRIPLE: (Subject, Predicate, Object)
+    const ttlData = `
+        @prefix ex: <http://example.org/> .
+        @prefix foaf: <http://xmlns.com/foaf/0.1/> .
+        @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+        # Triple: (ex:alice, rdf:type, foaf:Person)
+        ex:alice a foaf:Person ;
+            foaf:name "Alice Smith" ;
+            foaf:age 30 .
+
+        # Triple: (ex:bob, foaf:knows, ex:alice)
+        ex:bob a foaf:Person ;
+            foaf:name "Bob Jones" ;
+            foaf:knows ex:alice .
+
+        # Triple with typed literal
+        ex:acme a ex:Company ;
+            ex:name "Acme Corp" ;
+            ex:revenue "5000000"^^xsd:decimal .
+    `;
+
+    db.loadTtl(ttlData, null);
+
+    console.log('  Loaded RDF triples:');
+    console.log('    (ex:alice, a, foaf:Person)');
+    console.log("    (ex:alice, foaf:name, 'Alice Smith')");
+    console.log('    (ex:bob, foaf:knows, ex:alice)');
+    console.log('    (ex:acme, ex:revenue, 5000000^^xsd:decimal)');
+    console.log();
+
+    // Named graph (QUAD) - data isolation
+    console.log('  Named Graphs (Quads):');
+    console.log('    Data can be isolated in named graphs for access control');
+
+    const hrData = `
+        @prefix ex: <http://example.org/> .
+        ex:alice ex:salary 120000 .
+    `;
+
+    // Load into named graph (4th element)
+    db.loadTtl(hrData, 'http://example.org/hr-confidential');
+
+    console.log('    (ex:alice, ex:salary, 120000) -> GRAPH <hr-confidential>');
+    console.log();
+
+    // Count triples
+    const count = db.countTriples();
+    console.log(`  Total triples in database: ${count}`);
+    console.log();
+
+    return db;
+}
+
+// =============================================================================
+// 2. DATA INGESTION (Step 0): Trigger-Based Embedding Generation
+// =============================================================================
+
+function demoDataIngestion(db: any): any {
+    console.log('='.repeat(70));
+    console.log('  2. DATA INGESTION (Step 0): Trigger-Based Embeddings');
+    console.log('='.repeat(70));
+    console.log();
+
+    console.log('  Data Ingestion Flow:');
+    console.log();
+    console.log('    Raw RDF Data');
+    console.log('         |');
+    console.log('         v');
+    console.log('    +------------------+');
+    console.log('    | RDF Parser       |  TTL/N-Triples/JSON-LD');
+    console.log('    +------------------+');
+    console.log('         |');
+    console.log('         v');
+    console.log('    +------------------+');
+    console.log('    | Dictionary       |  String interning (8-byte IDs)');
+    console.log('    +------------------+');
+    console.log('         |');
+    console.log('         +--------+--------+');
+    console.log('         |        |        |');
+    console.log('         v        v        v');
+    console.log('    +------+  +------+  +------+');
+    console.log('    | SPOC |  |Trigger|  |Schema|');
+    console.log('    |Index |  |System |  |Index |');
+    console.log('    +------+  +------+  +------+');
+    console.log('                 |');
+    console.log('                 v');
+    console.log('    +------------------+');
+    console.log('    | Embedding        |  OpenAI / Anthropic / Ollama');
+    console.log('    | Providers        |');
+    console.log('    +------------------+');
+    console.log('                 |');
+    console.log('                 v');
+    console.log('    +------------------+');
+    console.log('    | HNSW Index       |  O(log N) similarity search');
+    console.log('    +------------------+');
+    console.log();
+
+    // Load fraud detection data
+    const fraudData = `
+        @prefix fraud: <http://example.org/fraud/> .
+        @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+        fraud:tx001 a fraud:Transaction ;
+            fraud:sender fraud:account001 ;
+            fraud:receiver fraud:account002 ;
+            fraud:amount "50000"^^xsd:decimal ;
+            fraud:timestamp "2024-12-14T10:30:00Z"^^xsd:dateTime .
+
+        fraud:tx002 a fraud:Transaction ;
+            fraud:sender fraud:account002 ;
+            fraud:receiver fraud:account003 ;
+            fraud:amount "48000"^^xsd:decimal .
+
+        fraud:tx003 a fraud:Transaction ;
+            fraud:sender fraud:account003 ;
+            fraud:receiver fraud:account001 ;
+            fraud:amount "45000"^^xsd:decimal .
+
+        fraud:account001 a fraud:Account ;
+            fraud:holder "Entity A" ;
+            fraud:jurisdiction "Panama" .
+
+        fraud:account002 a fraud:Account ;
+            fraud:holder "Entity B" ;
+            fraud:jurisdiction "BVI" .
+
+        fraud:account003 a fraud:Account ;
+            fraud:holder "Entity C" ;
+            fraud:jurisdiction "Cayman Islands" .
+    `;
+
+    db.loadTtl(fraudData, null);
+
+    console.log('  Loaded fraud detection data:');
+    console.log('    - 3 transactions (circular payment pattern)');
+    console.log('    - 3 accounts (offshore jurisdictions)');
+    console.log();
+    console.log('  In production, triggers would:');
+    console.log('    1. Generate embeddings for each entity');
+    console.log('    2. Update HNSW index for similarity search');
+    console.log('    3. Populate 1-hop neighbor cache');
+    console.log();
+
+    return db;
+}
+
+// =============================================================================
+// 3. SPARQL QUERIES: Declarative Graph Querying
+// =============================================================================
+
+function demoSparqlQueries(db: any): void {
+    console.log('='.repeat(70));
+    console.log('  3. SPARQL QUERIES: Declarative Graph Querying');
+    console.log('='.repeat(70));
+    console.log();
+
+    // Basic SELECT query
+    console.log('  Example 1: Basic SELECT');
+    console.log('  -------------------------');
+    const query1 = `
+        PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+        SELECT ?name ?age WHERE {
+            ?person a foaf:Person ;
+                    foaf:name ?name .
+            OPTIONAL { ?person foaf:age ?age }
+        }
+    `;
+    console.log(`  Query: ${query1.trim()}`);
+
+    const results = db.querySelect(query1);
+    console.log('  Results:');
+    for (const r of results) {
+        console.log(`    - ${JSON.stringify(r.bindings)}`);
+    }
+    console.log();
+
+    // Pattern matching - circular payments
+    console.log('  Example 2: Pattern Matching (Circular Payments)');
+    console.log('  ------------------------------------------------');
+    const query2 = `
+        PREFIX fraud: <http://example.org/fraud/>
+        SELECT ?a ?b ?c WHERE {
+            ?tx1 fraud:sender ?a ; fraud:receiver ?b .
+            ?tx2 fraud:sender ?b ; fraud:receiver ?c .
+            ?tx3 fraud:sender ?c ; fraud:receiver ?a .
+        }
+    `;
+    console.log('  Query: Find A -> B -> C -> A patterns');
+
+    const results2 = db.querySelect(query2);
+    console.log(`  Found ${results2.length} circular pattern(s)`);
+    console.log();
+}
+
+// =============================================================================
+// 4. DATALOG REASONING: Recursive Rules
+// =============================================================================
+
+function demoDatalogReasoning(): void {
+    console.log('='.repeat(70));
+    console.log('  4. DATALOG REASONING: Recursive Rules');
+    console.log('='.repeat(70));
+    console.log();
+
+    const engine = new DatalogEngine();
+
+    // Add facts
+    console.log('  Facts (parent relationship):');
+    engine.addFact('parent', ['alice', 'bob']);
+    engine.addFact('parent', ['bob', 'charlie']);
+    engine.addFact('parent', ['charlie', 'david']);
+    console.log('    parent(alice, bob)');
+    console.log('    parent(bob, charlie)');
+    console.log('    parent(charlie, david)');
+    console.log();
+
+    // Add recursive rules
+    console.log('  Rules (transitive closure):');
+    console.log('    ancestor(X, Y) :- parent(X, Y)              % base case');
+    console.log('    ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z)  % recursive');
+    console.log();
+
+    // Base case
+    engine.addRule('ancestor', ['X', 'Y'], [
+        { predicate: 'parent', args: ['X', 'Y'] }
+    ]);
+
+    // Recursive case
+    engine.addRule('ancestor', ['X', 'Z'], [
+        { predicate: 'parent', args: ['X', 'Y'] },
+        { predicate: 'ancestor', args: ['Y', 'Z'] }
+    ]);
+
+    // Evaluate
+    const iterations = engine.evaluateSemiNaive();
+    console.log(`  Semi-naive evaluation completed in ${iterations} iterations`);
+    console.log();
+
+    // Query
+    const results = engine.query('ancestor', ['alice', '?descendant']);
+    console.log('  Query: ancestor(alice, ?descendant)');
+    console.log('  Results:');
+    for (const r of results) {
+        console.log(`    - alice is ancestor of ${r.descendant}`);
+    }
+    console.log();
+}
+
+// =============================================================================
+// 5. EMBEDDINGS: Similarity Search
+// =============================================================================
+
+function demoEmbeddings(): void {
+    console.log('='.repeat(70));
+    console.log('  5. EMBEDDINGS: Similarity Search');
+    console.log('='.repeat(70));
+    console.log();
+
+    console.log('  Embedding Space Visualization (2D):');
+    console.log();
+    console.log('                    ^ dim2');
+    console.log('                    |');
+    console.log('              * FraudPattern1');
+    console.log('            * FraudPattern2');
+    console.log('                    |');
+    console.log('      o Person1     |');
+    console.log('    o Person2       |           + Company1');
+    console.log('                    |        + Company2');
+    console.log('    ----------------+-------------------> dim1');
+    console.log();
+    console.log('  Similar entities cluster together!');
+    console.log();
+
+    console.log('  HNSW Index:');
+    console.log('    - O(log N) search instead of O(N) brute force');
+    console.log('    - Multi-layer navigable small world graph');
+    console.log('    - ~50-100 bytes per vector + graph structure');
+    console.log();
+}
+
+// =============================================================================
+// 6. GRAPHFRAMES: Graph Algorithms
+// =============================================================================
+
+function demoGraphFrames(): void {
+    console.log('='.repeat(70));
+    console.log('  6. GRAPHFRAMES: Graph Algorithms');
+    console.log('='.repeat(70));
+    console.log();
+
+    console.log('  Available Algorithms:');
+    console.log('    - pageRank(): Node importance ranking');
+    console.log('    - connectedComponents(): Find isolated subgraphs');
+    console.log('    - shortestPaths(): Path finding');
+    console.log('    - triangleCount(): Clustering coefficient');
+    console.log('    - labelPropagation(): Community detection');
+    console.log('    - find(): Motif pattern matching');
+    console.log();
+
+    console.log('  Motif Pattern Matching:');
+    console.log('    Pattern: (a)-[e1]->(b); (b)-[e2]->(c); (c)-[e3]->(a)');
+    console.log('    Finds: All triangles in the graph');
+    console.log();
+}
+
+// =============================================================================
+// 7. CONCEPT LOOKUP: The Cmd+/ Analogy
+// =============================================================================
+
+function demoConceptLookup(): void {
+    console.log('='.repeat(70));
+    console.log('  7. CONCEPT LOOKUP: The Cmd+/ Analogy');
+    console.log('='.repeat(70));
+    console.log();
+
+    console.log('  IDE Symbol Search (Cmd+/):');
+    console.log('  ---------------------------');
+    console.log("    Developer: 'I need to validate an email'");
+    console.log('    IDE: Searches symbol table');
+    console.log('    Results: validateEmail(), isEmailValid(), EmailValidator');
+    console.log();
+
+    console.log('  HyperMind Concept Lookup:');
+    console.log('  ---------------------------');
+    console.log("    Agent: 'Find circular payment patterns'");
+    console.log();
+    console.log('    Step 1: Extract concepts');
+    console.log("      -> ['circular', 'payment', 'pattern']");
+    console.log();
+    console.log('    Step 2: Embed concepts');
+    console.log('      -> [0.12, 0.45, ...], [0.08, 0.51, ...]');
+    console.log();
+    console.log('    Step 3: Search schema index');
+    console.log('      -> HNSW similarity search');
+    console.log();
+    console.log('    Step 4: Return matches');
+    console.log('      -> Transaction (0.92), CircularTransfer (0.95)');
+    console.log();
+}
+
+// =============================================================================
+// 8. HYPERMIND AGENTS: Natural Language to Execution
+// =============================================================================
+
+function demoHyperMindAgents(): void {
+    console.log('='.repeat(70));
+    console.log('  8. HYPERMIND AGENTS: Natural Language to Execution');
+    console.log('='.repeat(70));
+    console.log();
+
+    console.log('  Agent Execution Flow:');
+    console.log('  ----------------------');
+    console.log();
+    console.log("    'Find circular payment patterns over $10,000'");
+    console.log('                     |');
+    console.log('                     v');
+    console.log('    +-----------------------------------+');
+    console.log('    |        LLM Planning Layer         |');
+    console.log('    |   Generate typed tool sequence    |');
+    console.log('    +-----------------------------------+');
+    console.log('                     |');
+    console.log('         +-----------+-----------+');
+    console.log('         |           |           |');
+    console.log('         v           v           v');
+    console.log('    +--------+  +--------+  +--------+');
+    console.log('    |sparql. |  | motif. |  |datalog.|');
+    console.log('    | query  |  |  find  |  | apply  |');
+    console.log('    +--------+  +--------+  +--------+');
+    console.log();
+
+    console.log('  Category Theory - Tools as Morphisms:');
+    console.log('  --------------------------------------');
+    console.log('    kg.sparql.query : Query -> BindingSet');
+    console.log('    kg.motif.find   : Pattern -> PatternSet');
+    console.log('    Composition: (f ; g) : A -> C');
+    console.log();
+
+    console.log('  Agent Creation (TypeScript):');
+    console.log('  ------------------------------');
+    console.log(`
+    import { spawn, AgentSpec, Model } from 'rust-kgdb';
+
+    const agent = await spawn({
+        name: 'fraud-detector',
+        model: Model.Claude('claude-3-opus'),
+        tools: [
+            'kg.sparql.query',
+            'kg.motif.find',
+            'kg.datalog.apply',
+        ],
+        maxIterations: 10,
+        tracingEnabled: true,
+        wasmSandbox: true,
+    });
+
+    const result = await agent.call('Find circular payments');
+    await agent.exportTrace('audit.json');
+    `);
+    console.log();
+}
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+async function main() {
+    console.log();
+    console.log('#'.repeat(70));
+    console.log('#' + ' '.repeat(68) + '#');
+    console.log('#' + '    RUST-KGDB CORE CONCEPTS DEMO'.padStart(47).padEnd(68) + '#');
+    console.log('#' + ' '.repeat(68) + '#');
+    console.log('#' + '    A complete walkthrough of all core concepts'.padStart(55).padEnd(68) + '#');
+    console.log('#' + '    See docs/CORE_CONCEPTS.md for detailed explanations'.padStart(60).padEnd(68) + '#');
+    console.log('#' + ' '.repeat(68) + '#');
+    console.log('#'.repeat(70));
+    console.log();
+
+    try {
+        // 1. Data Model
+        let db = demoDataModel();
+
+        // 2. Data Ingestion (Step 0)
+        db = demoDataIngestion(db);
+
+        // 3. SPARQL Queries
+        demoSparqlQueries(db);
+
+        // 4. Datalog Reasoning
+        demoDatalogReasoning();
+
+        // 5. Embeddings
+        demoEmbeddings();
+
+        // 6. GraphFrames
+        demoGraphFrames();
+
+        // 7. Concept Lookup
+        demoConceptLookup();
+
+        // 8. HyperMind Agents
+        demoHyperMindAgents();
+
+        console.log();
+        console.log('#'.repeat(70));
+        console.log('#' + ' '.repeat(68) + '#');
+        console.log('#' + '    ALL CONCEPTS DEMONSTRATED SUCCESSFULLY!'.padStart(52).padEnd(68) + '#');
+        console.log('#' + ' '.repeat(68) + '#');
+        console.log('#' + '    Next steps:'.padStart(25).padEnd(68) + '#');
+        console.log('#' + '    - Read docs/CORE_CONCEPTS.md for details'.padStart(48).padEnd(68) + '#');
+        console.log('#' + '    - See sdks/*/examples/ for more examples'.padStart(48).padEnd(68) + '#');
+        console.log('#' + '    - Try hypermind-fraud-underwriter.ts'.padStart(45).padEnd(68) + '#');
+        console.log('#' + ' '.repeat(68) + '#');
+        console.log('#'.repeat(70));
+        console.log();
+
+    } catch (error) {
+        console.error('Error:', error);
+        process.exit(1);
+    }
+}
+
+main();