rust-kgdb 0.6.81 → 0.6.82

package/examples/rpc-federation-sql-demo.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * ================================================================================
+ * RpcFederationProxy: Federated SQL Demo
+ * Cross-Database Queries via WASM RPC Proxy
+ * ================================================================================
+ *
+ * This demo showcases RpcFederationProxy from the rust-kgdb SDK:
+ * - Query across KGDB + Snowflake + BigQuery in single SQL statement
+ * - 7 Semantic UDFs (similar_to, neighbors, entity_type, etc.)
+ * - 9 Table Functions (graph_search, pagerank, vector_search, etc.)
+ * - Capability-based security with WasmSandbox
+ * - Full provenance tracking with audit log
+ *
+ * Architecture:
+ * - TypeScript SDK: Thin RPC proxy layer
+ * - Rust Core: Heavy lifting (DataFusion, Arrow, Vortex, HDRF partitioning)
+ *
+ * Run: node examples/rpc-federation-sql-demo.js
+ *
+ * @requires HyperFederate server running at http://localhost:30180
+ */
+
+const {
+  RpcFederationProxy,
+  FEDERATION_TOOLS,
+  GraphDB,
+  WasmSandbox,
+  ProofDAG
+} = require('../index.js')
+
+// ================================================================================
+// DEMO: Federated SQL Queries
+// ================================================================================
+
+async function runDemo() {
+  console.log('╔══════════════════════════════════════════════════════════════════════╗')
+  console.log('║     RpcFederationProxy: Federated SQL Demo                           ║')
+  console.log('║     Cross-Database Queries via WASM RPC Proxy                        ║')
+  console.log('╚══════════════════════════════════════════════════════════════════════╝\n')
+
+  // Create RpcFederationProxy with custom config
+  const federation = new RpcFederationProxy({
+    endpoint: process.env.HYPERFEDERATE_URL || 'http://localhost:30180',
+    timeout: 30000,
+    identityId: 'demo-user-001',
+    // WasmSandbox provides capability-based security
+    sandbox: new WasmSandbox({
+      capabilities: ['ReadKG', 'ExecuteTool', 'Federation'],
+      fuelLimit: 100000
+    })
+  })
+
+  console.log(`Federation Endpoint: ${federation.endpoint}`)
+  console.log(`Session ID: ${federation.sessionId}`)
+  console.log(`Identity ID: ${federation.identityId}`)
+  console.log(`Initial Fuel: ${federation.getFuelRemaining()}`)
+  console.log()
+
+  // ============================================================================
+  // 1. List available federation tools
+  // ============================================================================
+  console.log('1. Available Federation Tools (Category Theory: Typed Morphisms)')
+  console.log('═'.repeat(70))
+  for (const [name, tool] of Object.entries(FEDERATION_TOOLS)) {
+    console.log(`   ${name}`)
+    console.log(`     Input:  ${tool.input}`)
+    console.log(`     Output: ${tool.output}`)
+    console.log(`     Domain: ${tool.domain}`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 2. Simple SQL query
+  // ============================================================================
+  console.log('2. Simple SQL Query')
+  console.log('═'.repeat(70))
+  try {
+    const simpleResult = await federation.query('SELECT 1 + 2 as result, NOW() as timestamp')
+    console.log(`   Columns: ${simpleResult.columns.join(', ')}`)
+    console.log(`   Rows: ${JSON.stringify(simpleResult.rows, null, 2)}`)
+    console.log(`   Duration: ${simpleResult.duration}ms`)
+    console.log()
+  } catch (error) {
+    console.log(`   [Skipped - Server not running: ${error.message}]`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 3. KGDB + Snowflake Federation Query
+  // ============================================================================
+  console.log('3. KGDB + Snowflake Federation Query')
+  console.log('═'.repeat(70))
+  const kgSfQuery = `
+    -- Federation: KGDB (Knowledge Graph) + Snowflake (TPC-H)
+    WITH kg_entities AS (
+      SELECT * FROM graph_search('
+        PREFIX finance: <https://gonnect.ai/domains/finance#>
+        PREFIX tpch: <https://gonnect.ai/tpch#>
+        SELECT ?person ?custKey WHERE {
+          ?person a finance:Person ;
+                  tpch:custKey ?custKey .
+        } LIMIT 10
+      ')
+    )
+    SELECT
+      kg.person AS kg_entity,
+      kg.custKey,
+      sf.C_NAME,
+      sf.C_ACCTBAL
+    FROM kg_entities kg
+    JOIN snowflake_tpch.CUSTOMER sf
+      ON CAST(kg.custKey AS INTEGER) = sf.C_CUSTKEY
+    LIMIT 10
+  `
+  console.log(`   Query:\n${kgSfQuery.trim().split('\n').map(l => '   ' + l).join('\n')}`)
+  console.log()
+  try {
+    const result = await federation.query(kgSfQuery)
+    console.log(`   Result: ${result.rowCount} rows in ${result.duration}ms`)
+    console.log(`   Sources: ${result.metadata.sources?.join(', ')}`)
+    console.log()
+  } catch (error) {
+    console.log(`   [Demo mode - Server not running]`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 4. Three-Way Federation: KGDB + Snowflake + BigQuery
+  // ============================================================================
+  console.log('4. Three-Way Federation: KGDB + Snowflake + BigQuery')
+  console.log('═'.repeat(70))
+  const threeWayQuery = `
+    -- Three-way federation: KGDB + Snowflake + BigQuery
+    WITH
+    kg_risk AS (
+      SELECT * FROM graph_search('
+        PREFIX finance: <https://gonnect.ai/domains/finance#>
+        PREFIX tpch: <https://gonnect.ai/tpch#>
+        SELECT ?person ?custKey ?riskScore WHERE {
+          ?risk finance:assessedFor ?person ;
+                finance:riskScore ?riskScore .
+          ?person tpch:custKey ?custKey .
+          FILTER(?riskScore > 0.7)
+        } LIMIT 5
+      ')
+    ),
+    sf_cust AS (
+      SELECT C_CUSTKEY, C_NAME, C_ACCTBAL
+      FROM snowflake_tpch.CUSTOMER
+      LIMIT 100
+    )
+    SELECT
+      kg.person AS kg_entity,
+      kg.riskScore,
+      sf.C_NAME,
+      sf.C_ACCTBAL,
+      bq.name AS popular_name,
+      bq.number AS birth_count
+    FROM kg_risk kg
+    JOIN sf_cust sf ON CAST(kg.custKey AS INTEGER) = sf.C_CUSTKEY
+    LEFT JOIN bigquery_public.usa_1910_current bq
+      ON LOWER(SPLIT_PART(sf.C_NAME, ' ', 1)) = LOWER(bq.name)
+    WHERE bq.year = 2000
+    LIMIT 10
+  `
+  console.log(`   Query: Three-way federation across KGDB + Snowflake + BigQuery`)
+  console.log()
+
+  // ============================================================================
+  // 5. Semantic UDF Examples (7 AI-Powered Functions)
+  // ============================================================================
+  console.log('5. Semantic UDFs (7 AI-Powered Functions)')
+  console.log('═'.repeat(70))
+  const udfs = [
+    { name: 'similar_to', example: "similar_to('<http://ex.org/Entity1>', 0.7)" },
+    { name: 'text_search', example: "text_search('high risk fraud', 5)" },
+    { name: 'neighbors', example: "neighbors('<http://ex.org/Entity1>', 2)" },
+    { name: 'graph_pattern', example: "graph_pattern('<http://ex.org/Entity1>', NULL, NULL)" },
+    { name: 'sparql_query', example: "sparql_query('SELECT ?s WHERE { ?s a <http://ex.org/Person> }')" },
+    { name: 'entity_type', example: "entity_type('<http://ex.org/Entity1>')" },
+    { name: 'entity_properties', example: "entity_properties('<http://ex.org/Entity1>')" }
+  ]
+  for (const udf of udfs) {
+    console.log(`   ${udf.name}`)
+    console.log(`     Example: SELECT ${udf.example}`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 6. Table Functions (9 Graph Analytics)
+  // ============================================================================
+  console.log('6. Table Functions (9 Graph Analytics)')
+  console.log('═'.repeat(70))
+  const tableFunctions = [
+    { name: 'graph_search', desc: 'SPARQL → SQL bridge' },
+    { name: 'vector_search', desc: 'Semantic similarity search' },
+    { name: 'pagerank', desc: 'PageRank centrality' },
+    { name: 'connected_components', desc: 'Community detection' },
+    { name: 'shortest_paths', desc: 'Path finding' },
+    { name: 'triangle_count', desc: 'Graph density measure' },
+    { name: 'label_propagation', desc: 'Community detection' },
+    { name: 'datalog_reason', desc: 'Datalog inference' },
+    { name: 'motif_search', desc: 'Graph pattern matching' }
+  ]
+  for (const fn of tableFunctions) {
+    console.log(`   ${fn.name.padEnd(25)} - ${fn.desc}`)
+  }
+  console.log()
+
+  // ============================================================================
+  // 7. Audit Log (Provenance Tracking)
+  // ============================================================================
+  console.log('7. Audit Log (Provenance Tracking - Proof Theory)')
+  console.log('═'.repeat(70))
+  const auditLog = federation.getAuditLog()
+  console.log(`   Total entries: ${auditLog.length}`)
+  for (const entry of auditLog.slice(0, 3)) {
+    console.log(`   - Action: ${entry.action}`)
+    console.log(`     Duration: ${entry.duration}ms`)
+    console.log(`     Rows: ${entry.rows}`)
+    console.log(`     Timestamp: ${entry.timestamp}`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 8. ProofDAG with Federation Evidence
+  // ============================================================================
+  console.log('8. ProofDAG with Federation Evidence')
+  console.log('═'.repeat(70))
+  const proof = new ProofDAG('High-risk customers identified across 3 data sources')
+
+  // Add federation evidence to the proof
+  const fedNode = proof.addFederationEvidence(
+    proof.rootId,
+    threeWayQuery,
+    ['kgdb', 'snowflake', 'bigquery'],
+    42,  // rowCount
+    890, // duration
+    { planHash: 'abc123', cached: false }
+  )
+  console.log(`   Root claim: ${proof.rootClaim}`)
+  console.log(`   Proof hash: ${proof.computeHash()}`)
+  console.log(`   Verification: ${JSON.stringify(proof.verify())}`)
+  console.log()
+
+  // ============================================================================
+  // Summary
+  // ============================================================================
+  console.log('╔══════════════════════════════════════════════════════════════════════╗')
+  console.log('║     Demo Complete!                                                   ║')
+  console.log('╚══════════════════════════════════════════════════════════════════════╝')
+  console.log(`
+Key Capabilities Demonstrated:
+  - RpcFederationProxy: Thin SDK proxy to Rust HyperFederate server
+  - Cross-Database SQL: KGDB + Snowflake + BigQuery in single query
+  - 7 Semantic UDFs: AI-powered functions in SQL context
+  - 9 Table Functions: Graph analytics via SQL
+  - WasmSandbox: Capability-based security with fuel metering
+  - ProofDAG: Full provenance tracking (W3C PROV compatible)
+
+Architecture Principle:
+  - Heavy lifting in Rust core (DataFusion, Arrow, Vortex, HDRF)
+  - TypeScript SDK is thin RPC proxy layer
+  - Category Theory: Tools as typed morphisms (Input → Output)
+  - Proof Theory: Every answer has verifiable reasoning chain
+
+Fuel Remaining: ${federation.getFuelRemaining()}
+`)
+}
+
+// Run the demo
+runDemo().catch(console.error)

package/examples/rpc-virtual-tables-demo.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * ================================================================================
+ * RpcFederationProxy: Virtual Tables Demo
+ * Session-Bound Query Result Materialization
+ * ================================================================================
+ *
+ * Virtual Tables in HyperFederate:
+ * - Session-bound materialization of federation query results
+ * - Stored as RDF triples in KGDB (self-describing)
+ * - Access control via shared_with and shared_with_groups
+ * - Refresh policies: on_demand, ttl, on_source_change
+ * - No ETL required - real-time query materialization
+ *
+ * Architecture:
+ * - Heavy lifting in Rust core (DataFusion, Arrow, KGDB storage)
+ * - TypeScript SDK provides thin RPC proxy layer
+ *
+ * Run: node examples/rpc-virtual-tables-demo.js
+ *
+ * @requires HyperFederate server running at http://localhost:30180
+ */
+
+const {
+  RpcFederationProxy,
+  WasmSandbox,
+  ProofDAG
+} = require('../index.js')
+
+// ================================================================================
+// DEMO: Virtual Tables
+// ================================================================================
+
+async function runDemo() {
+  console.log('╔══════════════════════════════════════════════════════════════════════╗')
+  console.log('║     RpcFederationProxy: Virtual Tables Demo                          ║')
+  console.log('║     Session-Bound Query Result Materialization                       ║')
+  console.log('╚══════════════════════════════════════════════════════════════════════╝\n')
+
+  // Create RpcFederationProxy
+  const federation = new RpcFederationProxy({
+    endpoint: process.env.HYPERFEDERATE_URL || 'http://localhost:30180',
+    identityId: 'risk-analyst-001'
+  })
+
+  console.log(`Federation Endpoint: ${federation.endpoint}`)
+  console.log(`Session ID: ${federation.sessionId}`)
+  console.log(`Identity ID: ${federation.identityId}`)
+  console.log()
+
+  // ============================================================================
+  // 1. Create Virtual Table from Federation Query
+  // ============================================================================
+  console.log('1. Create Virtual Table from Federation Query')
+  console.log('═'.repeat(70))
+
+  const createVtQuery = `
+    -- High-risk customers: KGDB risk scores + Snowflake account data
+    SELECT
+      kg.person AS kg_entity,
+      kg.riskScore AS risk_level,
+      entity_type(kg.person) AS entity_types,
+      sf.C_NAME AS customer_name,
+      sf.C_ACCTBAL AS account_balance,
+      sf.C_MKTSEGMENT AS market_segment
+    FROM graph_search('
+      PREFIX finance: <https://gonnect.ai/domains/finance#>
+      PREFIX tpch: <https://gonnect.ai/tpch#>
+      SELECT ?person ?riskScore ?custKey WHERE {
+        ?risk finance:assessedFor ?person ;
+              finance:riskScore ?riskScore .
+        ?person tpch:custKey ?custKey .
+        FILTER(?riskScore > 0.7)
+      }
+    ') kg
+    JOIN snowflake_tpch.CUSTOMER sf
+      ON CAST(kg.custKey AS INTEGER) = sf.C_CUSTKEY
+    WHERE sf.C_ACCTBAL > 50000
+  `
+
+  console.log('   SQL Query:')
+  console.log(createVtQuery.trim().split('\n').map(l => '     ' + l).join('\n'))
+  console.log()
+
+  try {
+    const vt = await federation.createVirtualTable('high_risk_customers', createVtQuery, {
+      refreshPolicy: 'on_demand',
+      ttlSeconds: 3600,
+      sharedWith: ['risk-analyst-002', 'compliance-officer-001'],
+      sharedWithGroups: ['team-risk-analytics', 'team-compliance']
+    })
+
+    console.log('   Virtual Table Created:')
+    console.log(`     ID: ${vt.id}`)
+    console.log(`     Name: ${vt.name}`)
+    console.log(`     URI: ${vt.uri}`)
+    console.log(`     Columns: ${vt.columns.join(', ')}`)
+    console.log(`     Row Count: ${vt.rowCount}`)
+    console.log(`     Refresh Policy: ${vt.refreshPolicy}`)
+    console.log(`     Created At: ${vt.createdAt}`)
+    console.log()
+  } catch (error) {
+    console.log(`   [Demo mode - Server not running]`)
+    console.log(`   Virtual table would be created with:`)
+    console.log(`     Name: high_risk_customers`)
+    console.log(`     Refresh Policy: on_demand`)
+    console.log(`     TTL: 3600 seconds`)
+    console.log(`     Shared With: risk-analyst-002, compliance-officer-001`)
+    console.log(`     Shared Groups: team-risk-analytics, team-compliance`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 2. Query Virtual Table (No Re-execution)
+  // ============================================================================
+  console.log('2. Query Virtual Table (Materialized Results)')
+  console.log('═'.repeat(70))
+  console.log('   Virtual tables are materialized - no query re-execution needed.')
+  console.log()
+  console.log('   Query: SELECT * FROM virtual.high_risk_customers WHERE account_balance > 100000')
+  console.log()
+
+  try {
+    const result = await federation.queryVirtualTable('high_risk_customers', 'account_balance > 100000')
+    console.log(`   Result: ${result.rowCount} rows in ${result.duration}ms`)
+    console.log(`   (Materialized data, not re-executed)`)
+    console.log()
+  } catch (error) {
+    console.log(`   [Demo mode - Would query materialized virtual table]`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 3. Virtual Table Use Cases
+  // ============================================================================
+  console.log('3. Virtual Table Use Cases')
+  console.log('═'.repeat(70))
+  const useCases = [
+    {
+      name: 'Risk Dashboard',
+      query: `CREATE VIRTUAL TABLE risk_dashboard AS
+        SELECT entity, risk_score, neighbors(entity, 1) AS network
+        FROM high_risk_customers`,
+      refresh: 'ttl (5 min)',
+      shared: 'team-risk-analytics'
+    },
+    {
+      name: 'Compliance Audit',
+      query: `CREATE VIRTUAL TABLE compliance_audit AS
+        SELECT entity, risk_score, entity_properties(entity) AS all_props
+        FROM high_risk_customers WHERE risk_score > 0.9`,
+      refresh: 'on_source_change',
+      shared: 'compliance-officers'
+    },
+    {
+      name: 'Customer 360',
+      query: `CREATE VIRTUAL TABLE customer_360 AS
+        SELECT kg.*, sf.*, bq.name_popularity
+        FROM graph_search(...) kg
+        JOIN snowflake.CUSTOMER sf ON ...
+        LEFT JOIN bigquery.usa_names bq ON ...`,
+      refresh: 'on_demand',
+      shared: 'team-customer-success'
+    }
+  ]
+
+  for (const useCase of useCases) {
+    console.log(`   ${useCase.name}`)
+    console.log(`     Refresh: ${useCase.refresh}`)
+    console.log(`     Shared With: ${useCase.shared}`)
+    console.log()
+  }
+
+  // ============================================================================
+  // 4. Access Control Model
+  // ============================================================================
+  console.log('4. Access Control Model')
+  console.log('═'.repeat(70))
+  console.log(`
+   Virtual tables support fine-grained access control:
+
+   ┌─────────────────────────────────────────────────────────────────────┐
+   │  Virtual Table: high_risk_customers                                 │
+   │  Owner: risk-analyst-001 (creator)                                  │
+   ├─────────────────────────────────────────────────────────────────────┤
+   │  shared_with (individuals):                                         │
+   │    - risk-analyst-002        [Full access]                          │
+   │    - compliance-officer-001  [Full access]                          │
+   │                                                                     │
+   │  shared_with_groups (teams):                                        │
+   │    - team-risk-analytics     [All members have access]              │
+   │    - team-compliance         [All members have access]              │
+   └─────────────────────────────────────────────────────────────────────┘
+
+   Access check: has_access(identity_id, groups) → boolean
+  `)
+
+  // ============================================================================
+  // 5. RDF Storage (Self-Describing)
+  // ============================================================================
+  console.log('5. Virtual Table RDF Storage (Self-Describing)')
+  console.log('═'.repeat(70))
+  console.log(`
+   Virtual tables are stored as RDF triples in KGDB:
+
+   <urn:hyperfederate:vt:${federation.sessionId}:high_risk_customers>
+       a hf:VirtualTable ;
+       hf:name "high_risk_customers" ;
+       hf:sessionId "${federation.sessionId}" ;
+       hf:ownerId "${federation.identityId}" ;
+       hf:query "SELECT kg.person, kg.riskScore..." ;
+       hf:refreshPolicy "on_demand" ;
+       hf:rowCount "42"^^xsd:integer ;
+       hf:createdAt "2024-12-21T12:00:00Z"^^xsd:dateTime ;
+       hf:sourceLineage "kgdb", "snowflake" ;
+       hf:sharedWith "risk-analyst-002", "compliance-officer-001" ;
+       hf:sharedWithGroups "team-risk-analytics", "team-compliance" .
+
+   This makes virtual tables queryable via SPARQL!
+  `)
+
+  // ============================================================================
+  // 6. ProofDAG Integration
+  // ============================================================================
+  console.log('6. ProofDAG Integration (Provenance Tracking)')
+  console.log('═'.repeat(70))
+
+  const proof = new ProofDAG('Risk analysis for high-value customers')
+
+  // Add virtual table creation as evidence
+  const vtNode = proof.addVirtualTableEvidence(
+    proof.rootId,
+    'high_risk_customers',
+    createVtQuery,
+    42  // rowCount
+  )
+
+  console.log(`   Root claim: ${proof.rootClaim}`)
+  console.log(`   Evidence type: virtual_table`)
+  console.log(`   Proof hash: ${proof.computeHash()}`)
+  console.log()
+
+  // ============================================================================
+  // Summary
+  // ============================================================================
+  console.log('╔══════════════════════════════════════════════════════════════════════╗')
+  console.log('║     Demo Complete!                                                   ║')
+  console.log('╚══════════════════════════════════════════════════════════════════════╝')
+  console.log(`
+Virtual Table Benefits:
+  - No ETL Pipeline: Real-time query materialization
+  - Session Isolation: Each user sees only their tables
+  - Access Control: Fine-grained sharing via identities/groups
+  - Self-Describing: Stored as RDF, queryable via SPARQL
+  - Refresh Policies: on_demand, ttl, on_source_change
+  - Provenance: Full lineage tracking via ProofDAG
+
+Architecture Principle:
+  - Materialization logic in Rust core (DataFusion + KGDB)
+  - TypeScript SDK provides thin RPC proxy layer
+  - Heavy computation happens server-side
+
+Audit Log Entries: ${federation.getAuditLog().length}
+`)
+}
+
+// Run the demo
+runDemo().catch(console.error)