From efababe3975fe21fa46c5775d42e93917cde5a47 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Mon, 23 Jun 2025 11:26:11 -0700
Subject: [PATCH] **feat(demo): add GitHub Pages demo script and update
 deployment workflow**

### Changes:
- **`demo/simplified-augmentations-gh-pages.js`**:
  - Added a new demo script showcasing simplified augmentations for GitHub Pages.
  - Includes examples for static and streaming data processing, WebSocket support, and dynamic augmentation loading.

- **`README.md`**:
  - Updated the demo link to point directly to `https://soulcraft-research.github.io/brainy/`.

- **`.github/workflows/deploy-demo.yml`**:
  - Enhanced the deployment workflow to include the `simplified-augmentations-gh-pages.js` file as the GitHub Pages demo entry point.
  - Added steps to copy and prepare required `dist` files during the build process.

- **`demo/index.html`**:
  - Dynamically adjusted the import path for the Brainy library to support both local and CDN environments.
  - Reformatted code for readability and alignment with deployment needs.

### Purpose:
Introduced a tailored demonstration script for GitHub Pages to highlight Brainy's streamlined augmentation features. Enhanced the deployment pipeline for better integration and seamless live demo experience.
---
 .github/workflows/deploy-demo.yml         |   7 +
 README.md                                 |   2 +-
 demo/index.html                           |  21 +-
 demo/simplified-augmentations-gh-pages.js | 390 ++++++++++++++++++++++
 4 files changed, 412 insertions(+), 8 deletions(-)
 create mode 100644 demo/simplified-augmentations-gh-pages.js

diff --git a/.github/workflows/deploy-demo.yml b/.github/workflows/deploy-demo.yml
index 10b4e5ed..d9ddcc08 100644
--- a/.github/workflows/deploy-demo.yml
+++ b/.github/workflows/deploy-demo.yml
@@ -27,6 +27,13 @@ jobs:
         run: |
           npm run build
           npm run build:browser
+          mkdir -p demo/dist
+          cp dist/unified.js demo/dist/
+          cp dist/unified.min.js demo/dist/
+          cp dist/brainy.js demo/dist/
+          cp dist/brainy.min.js demo/dist/
+          # Use the GitHub Pages specific version of simplified-augmentations.js
+          cp demo/simplified-augmentations-gh-pages.js demo/simplified-augmentations.js
 
       - name: Deploy to GitHub Pages 🚀
         uses: JamesIves/github-pages-deploy-action@v4
diff --git a/README.md b/README.md
index 33fb425a..117de6ad 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@ it gets - learning from your data to provide increasingly relevant results and c
 
 ## 🚀 Live Demo
 
-**[Try the live demo](https://soulcraft-research.github.io/brainy/examples/)** - Check out the interactive demo on
+**[Try the live demo](https://soulcraft-research.github.io/brainy/)** - Check out the interactive demo on
 GitHub Pages that showcases Brainy's main features.
 
 ## 📊 What Can You Build?
diff --git a/demo/index.html b/demo/index.html
index 23bf8c24..a63814bc 100644
--- a/demo/index.html
+++ b/demo/index.html
@@ -1091,8 +1091,15 @@ await db.init()
 </div>
 
 <script type="module">
-  // Import Brainy library directly as a module
-  import { BrainyData, NounType, VerbType } from 'https://cdn.jsdelivr.net/npm/@soulcraft/brainy/dist/unified.js'
+  // Dynamically determine the import path based on the environment
+  // If running on GitHub Pages, use the local files, otherwise use the CDN
+  const isGitHubPages = window.location.hostname.includes('github.io')
+  const importPath = isGitHubPages
+    ? './dist/unified.js'
+    : 'https://cdn.jsdelivr.net/npm/@soulcraft/brainy/dist/unified.js'
+
+  // Dynamic import to handle different environments
+  const { BrainyData, NounType, VerbType } = await import(importPath)
 
   // Make BrainyData and types available globally
   window.BrainyData = BrainyData
@@ -3363,7 +3370,7 @@ await db.init()
 
   function updateSearchVisualization(results) {
     // This function is now disabled as per requirements to remove the visual graph
-    return;
+    return
 
     // Create SVG container
     const svg = d3.select(graphContainer)
@@ -3417,8 +3424,8 @@ await db.init()
         const currentTransform = d3.zoomTransform(svg.node())
         svg.transition()
           .duration(300)
-          .call(zoomBehavior.transform, 
-                d3.zoomIdentity.translate(currentTransform.x, currentTransform.y).scale(currentTransform.k * 1.3))
+          .call(zoomBehavior.transform,
+            d3.zoomIdentity.translate(currentTransform.x, currentTransform.y).scale(currentTransform.k * 1.3))
       })
     }
 
@@ -3427,8 +3434,8 @@ await db.init()
         const currentTransform = d3.zoomTransform(svg.node())
         svg.transition()
           .duration(300)
-          .call(zoomBehavior.transform, 
-                d3.zoomIdentity.translate(currentTransform.x, currentTransform.y).scale(currentTransform.k / 1.3))
+          .call(zoomBehavior.transform,
+            d3.zoomIdentity.translate(currentTransform.x, currentTransform.y).scale(currentTransform.k / 1.3))
       })
     }
 
diff --git a/demo/simplified-augmentations-gh-pages.js b/demo/simplified-augmentations-gh-pages.js
new file mode 100644
index 00000000..44740ba3
--- /dev/null
+++ b/demo/simplified-augmentations-gh-pages.js
@@ -0,0 +1,390 @@
+/**
+ * Simplified Augmentations Example for GitHub Pages
+ *
+ * This example demonstrates how to use the simplified augmentation factory and streamlined pipeline
+ * to create, import, and execute augmentations for both static and streaming data.
+ */
+
+import {
+  // Augmentation factory
+  createMemoryAugmentation,
+  createConduitAugmentation,
+  createSenseAugmentation,
+  addWebSocketSupport,
+  loadAugmentationModule,
+
+  // Streamlined pipeline
+  processStaticData,
+  processStreamingData,
+  createPipeline,
+  createStreamingPipeline,
+  executeStreamlined,
+  executeByType,
+  executeSingle,
+  StreamlinedExecutionMode,
+
+  // Core types
+  AugmentationType
+} from './dist/brainy.js'
+
+/**
+ * Example 1: Creating a simple memory augmentation
+ */
+async function example1() {
+  console.log('Example 1: Creating a simple memory augmentation')
+
+  // Create a memory augmentation with the factory
+  const memoryAug = createMemoryAugmentation({
+    name: 'simple-memory',
+    description: 'A simple in-memory storage augmentation',
+    autoRegister: true,
+    autoInitialize: true,
+
+    // Implement the required methods
+    storeData: async (key, data) => {
+      console.log(`Storing data for key: ${key}`)
+      // In a real implementation, you would store the data somewhere
+      return {
+        success: true,
+        data: true
+      }
+    },
+
+    retrieveData: async (key) => {
+      console.log(`Retrieving data for key: ${key}`)
+      // In a real implementation, you would retrieve the data from storage
+      return {
+        success: true,
+        data: { example: 'data', key }
+      }
+    }
+  })
+
+  // Use the augmentation directly
+  const storeResult = await executeSingle(memoryAug, 'storeData', 'test-key', {
+    value: 'test-value'
+  })
+  console.log('Store result:', storeResult)
+
+  const retrieveResult = await executeSingle(
+    memoryAug,
+    'retrieveData',
+    'test-key'
+  )
+  console.log('Retrieve result:', retrieveResult)
+
+  console.log('-----------------------------------')
+}
+
+/**
+ * Example 2: Creating a WebSocket-enabled conduit augmentation
+ */
+async function example2() {
+  console.log('Example 2: Creating a WebSocket-enabled conduit augmentation')
+
+  // Create a basic conduit augmentation
+  const conduitAug = createConduitAugmentation({
+    name: 'simple-conduit',
+    description: 'A simple conduit augmentation',
+
+    // Implement the required methods
+    readData: async (query) => {
+      console.log(`Reading data with query:`, query)
+      return {
+        success: true,
+        data: { result: 'some data' }
+      }
+    },
+
+    writeData: async (data) => {
+      console.log(`Writing data:`, data)
+      return {
+        success: true,
+        data: { written: true }
+      }
+    }
+  })
+
+  // Add WebSocket support to the conduit augmentation
+  const wsConduitAug = addWebSocketSupport(conduitAug, {
+    connectWebSocket: async (url) => {
+      console.log(`Connecting to WebSocket at ${url}`)
+      // In a real implementation, you would establish a WebSocket connection
+      return {
+        connectionId: 'ws-1',
+        url,
+        status: 'connected'
+      }
+    },
+
+    sendWebSocketMessage: async (connectionId, data) => {
+      console.log(`Sending message on connection ${connectionId}:`, data)
+      // In a real implementation, you would send the message over the WebSocket
+    }
+  })
+
+  // Use the WebSocket-enabled augmentation
+  const connectResult = await executeSingle(
+    wsConduitAug,
+    'connectWebSocket',
+    'wss://example.com'
+  )
+  console.log('Connect result:', connectResult)
+
+  await executeSingle(wsConduitAug, 'sendWebSocketMessage', 'ws-1', {
+    type: 'hello'
+  })
+
+  console.log('-----------------------------------')
+}
+
+/**
+ * Example 3: Processing static data through a pipeline
+ */
+async function example3() {
+  console.log('Example 3: Processing static data through a pipeline')
+
+  // Create a sense augmentation for processing raw data
+  const senseAug = createSenseAugmentation({
+    name: 'text-processor',
+    description: 'Processes text into nouns and verbs',
+
+    processRawData: (rawData, dataType) => {
+      if (dataType !== 'text') {
+        return {
+          success: false,
+          data: { nouns: [], verbs: [] },
+          error: `Unsupported data type: ${dataType}`
+        }
+      }
+
+      const text = rawData.toString()
+      console.log(`Processing text: ${text}`)
+
+      // Simple example - in a real implementation, you would use NLP
+      const words = text.split(' ')
+      const nouns = words.filter((w) => w.length > 4)
+      const verbs = words.filter((w) => w.length <= 4)
+
+      return {
+        success: true,
+        data: { nouns, verbs }
+      }
+    }
+  })
+
+  // Create a perception augmentation for interpreting the processed data
+  const perceptionAug = createMemoryAugmentation({
+    name: 'text-interpreter',
+    description: 'Interprets processed text data',
+
+    storeData: async (key, data) => {
+      console.log(`Interpreting data:`, data)
+
+      // Simple example - in a real implementation, you would do more sophisticated interpretation
+      return {
+        success: true,
+        data: {
+          interpreted: true,
+          nounCount: data.nouns.length,
+          verbCount: data.verbs.length,
+          summary: `Found ${data.nouns.length} nouns and ${data.verbs.length} verbs`
+        }
+      }
+    }
+  })
+
+  // Process static data through a pipeline
+  const result = await processStaticData(
+    'This is an example text for processing through the pipeline',
+    [
+      {
+        augmentation: senseAug,
+        method: 'processRawData',
+        transformArgs: (data) => [data, 'text']
+      },
+      {
+        augmentation: perceptionAug,
+        method: 'storeData',
+        transformArgs: (data) => ['processed-text', data]
+      }
+    ]
+  )
+
+  console.log('Pipeline result:', result)
+
+  // Create a reusable pipeline
+  const textPipeline = createPipeline([
+    {
+      augmentation: senseAug,
+      method: 'processRawData',
+      transformArgs: (data) => [data, 'text']
+    },
+    {
+      augmentation: perceptionAug,
+      method: 'storeData',
+      transformArgs: (data) => ['processed-text', data]
+    }
+  ])
+
+  // Use the reusable pipeline
+  const result2 = await textPipeline(
+    'Another example text for the reusable pipeline'
+  )
+  console.log('Reusable pipeline result:', result2)
+
+  console.log('-----------------------------------')
+}
+
+/**
+ * Example 4: Processing streaming data
+ */
+async function example4() {
+  console.log('Example 4: Processing streaming data')
+
+  // Create a sense augmentation that can listen to a data feed
+  const streamingSenseAug = createSenseAugmentation({
+    name: 'stream-processor',
+    description: 'Processes streaming data',
+
+    listenToFeed: async (feedUrl, callback) => {
+      console.log(`Listening to feed at ${feedUrl}`)
+
+      // Simulate streaming data with setInterval
+      const interval = setInterval(() => {
+        const timestamp = new Date().toISOString()
+        console.log(`Received data from feed at ${timestamp}`)
+
+        // Send data to the callback
+        callback({
+          nouns: [`data-${Date.now()}`, 'stream', 'example'],
+          verbs: ['is', 'runs', 'processes']
+        })
+      }, 2000)
+
+      // In a real implementation, you would return a way to stop the stream
+      // For this example, we'll stop after 3 iterations
+      setTimeout(() => {
+        clearInterval(interval)
+        console.log('Stream ended')
+      }, 7000)
+    }
+  })
+
+  // Create a perception augmentation for processing the streaming data
+  const streamingPerceptionAug = createMemoryAugmentation({
+    name: 'stream-interpreter',
+    description: 'Interprets streaming data',
+
+    storeData: async (key, data) => {
+      console.log(`Processing streaming data:`, data)
+
+      return {
+        success: true,
+        data: {
+          processed: true,
+          timestamp: new Date().toISOString(),
+          nounCount: data.nouns.length,
+          verbCount: data.verbs.length
+        }
+      }
+    }
+  })
+
+  // Set up a streaming pipeline
+  await processStreamingData(
+    streamingSenseAug,
+    'listenToFeed',
+    ['http://example.com/data-feed'],
+    [
+      {
+        augmentation: streamingPerceptionAug,
+        method: 'storeData',
+        transformArgs: (data) => [`stream-${Date.now()}`, data]
+      }
+    ],
+    (result) => {
+      console.log('Streaming pipeline result:', result)
+    }
+  )
+
+  // Wait for the streaming example to complete
+  await new Promise((resolve) => setTimeout(resolve, 8000))
+
+  console.log('-----------------------------------')
+}
+
+/**
+ * Example 5: Dynamic loading of augmentations
+ */
+async function example5() {
+  console.log('Example 5: Dynamic loading of augmentations')
+
+  // Simulate dynamic loading of a module
+  // In a real application, you would use dynamic import()
+  const mockModulePromise = Promise.resolve({
+    dynamicMemoryAug: createMemoryAugmentation({
+      name: 'dynamic-memory',
+      description: 'Dynamically loaded memory augmentation',
+
+      storeData: async (key, data) => {
+        console.log(`[Dynamic] Storing data for key: ${key}`)
+        return {
+          success: true,
+          data: true
+        }
+      },
+
+      retrieveData: async (key) => {
+        console.log(`[Dynamic] Retrieving data for key: ${key}`)
+        return {
+          success: true,
+          data: { dynamic: true, key }
+        }
+      }
+    })
+  })
+
+  // Load the augmentations from the module
+  const loadedAugmentations = await loadAugmentationModule(mockModulePromise, {
+    autoRegister: true,
+    autoInitialize: true
+  })
+
+  console.log(`Loaded ${loadedAugmentations.length} augmentations dynamically`)
+
+  // Use the dynamically loaded augmentation
+  if (loadedAugmentations.length > 0) {
+    const dynamicAug = loadedAugmentations[0]
+    console.log(`Using dynamically loaded augmentation: ${dynamicAug.name}`)
+
+    const retrieveResult = await executeSingle(
+      dynamicAug,
+      'retrieveData',
+      'dynamic-key'
+    )
+    console.log('Dynamic retrieve result:', retrieveResult)
+  }
+
+  console.log('-----------------------------------')
+}
+
+/**
+ * Run all demo
+ */
+async function runExamples() {
+  try {
+    await example1()
+    await example2()
+    await example3()
+    await example4()
+    await example5()
+
+    console.log('All demo completed successfully!')
+  } catch (error) {
+    console.error('Error running demo:', error)
+  }
+}
+
+// Run the demo
+runExamples()