Implement backpropagation mechanism for bidirectional node communication

BACKPROPAGATION_DIAGRAM.md

@@ -0,0 +1,138 @@
+# Backpropagation Flow Diagram
+
+This diagram illustrates how backpropagation works in the flow execution system, showing both forward execution and backward propagation of data.
+
+## Flow Execution with Backpropagation
+
+```mermaid
+graph LR
+    subgraph "Forward Execution (White Program Counter)"
+        direction LR
+        A[Start Node<br/>Output: data] -->|Forward<br/>White| B[Processing Node<br/>Compute: process]
+        B -->|Forward<br/>White| C[End Node<br/>Compute: result]
+    end
+
+    subgraph "Backpropagation (Orange Program Counter)"
+        direction RL
+        C -.->|Backpropagate<br/>Orange| B
+        B -.->|Backpropagate<br/>Orange| A
+    end
+
+    style A fill:#e1f5ff
+    style B fill:#fff4e1
+    style C fill:#ffe1f5
+    style A stroke:#0066cc,stroke-width:2px
+    style B stroke:#cc6600,stroke-width:2px
+    style C stroke:#cc0066,stroke-width:2px
+```
+
+## Detailed Backpropagation Flow
+
+```mermaid
+sequenceDiagram
+    participant Start as Start Node
+    participant Process as Processing Node
+    participant End as End Node
+
+    Note over Start,End: Forward Execution (White Program Counter)
+    Start->>Process: Execute compute()<br/>Output: data
+    Process->>End: Execute compute()<br/>Output: result
+
+    Note over End,Start: Backpropagation (Orange Program Counter)
+    End->>End: Return {<br/>  result: value,<br/>  backpropagate: feedbackData<br/>}
+    End->>Process: backpropagate(feedbackData)
+    Process->>Process: Update internal state<br/>with feedbackData
+    Process->>Start: backpropagate(processedFeedback)
+    Start->>Start: Update internal state<br/>with processedFeedback
+```
+
+## Node Connection Visualization
+
+```mermaid
+graph TB
+    subgraph "Visual Representation"
+        direction LR
+        SN[Start Node<br/>🟦] -->|"→ Forward (White)"| PN[Processing Node<br/>🟨]
+        PN -->|"→ Forward (White)"| EN[End Node<br/>🟪]
+
+        EN -.->|"← Backpropagate (Orange)"| PN
+        PN -.->|"← Backpropagate (Orange)"| SN
+    end
+
+    style SN fill:#e1f5ff,stroke:#0066cc,stroke-width:3px
+    style PN fill:#fff4e1,stroke:#cc6600,stroke-width:3px
+    style EN fill:#ffe1f5,stroke:#cc0066,stroke-width:3px
+```
+
+## Complete Execution Cycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> ForwardExecution
+
+    state ForwardExecution {
+        [*] --> StartNode
+        StartNode --> ProcessingNode: Forward (White)
+        ProcessingNode --> EndNode: Forward (White)
+        EndNode --> CheckBackpropagation
+    }
+
+    state CheckBackpropagation {
+        [*] --> HasBackpropagation
+        HasBackpropagation --> BackwardExecution: Yes
+        HasBackpropagation --> [*]: No
+    }
+
+    state BackwardExecution {
+        [*] --> EndToProcess: Backpropagate (Orange)
+        EndToProcess --> ProcessToStart: Backpropagate (Orange)
+        ProcessToStart --> [*]
+    }
+
+    ForwardExecution --> CheckBackpropagation
+    BackwardExecution --> [*]
+```
+
+## Example: Neural Network Layer
+
+```mermaid
+graph LR
+    subgraph "Input Layer"
+        I1[Input Node 1<br/>Weights: w1, w2]
+        I2[Input Node 2<br/>Weights: w3, w4]
+    end
+
+    subgraph "Hidden Layer"
+        H[Hidden Node<br/>Activation: tanh]
+    end
+
+    subgraph "Output Layer"
+        O[Output Node<br/>Loss Calculation]
+    end
+
+    I1 -->|Forward| H
+    I2 -->|Forward| H
+    H -->|Forward| O
+
+    O -.->|Backpropagate<br/>Gradient: 0.15| H
+    H -.->|Backpropagate<br/>Gradient: 0.08| I1
+    H -.->|Backpropagate<br/>Gradient: 0.07| I2
+
+    style I1 fill:#e1f5ff
+    style I2 fill:#e1f5ff
+    style H fill:#fff4e1
+    style O fill:#ffe1f5
+```
+
+## Key Concepts
+
+1. **Forward Execution**: Normal flow execution with white program counter moving from start to end nodes
+2. **Backpropagation**: Reverse flow with orange program counter moving from end to start nodes
+3. **Data Flow**: 
+   - Forward: Output data flows from source to destination
+   - Backward: Feedback/gradient data flows from destination to source
+4. **Visual Indicators**:
+   - White cursor = Forward execution
+   - Orange cursor = Backpropagation
+   - No message bubble for backpropagation (only program counter)
+

IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,153 @@
+# Backpropagation Implementation - Summary
+
+## What Was Implemented
+
+This implementation adds a **backpropagation mechanism** to the web-flow-executor that allows nodes to send information back to their input nodes. This addresses the requirement to "implement backpropagation in web-flow-executor for node-types beside compute and computeAsync so that nodes can send information back to nodes so that it can change the local node state which can be used in the UI of the node or just its memory which will be used in a next triggering of that node's compute(Async) function."
+
+## How It Works
+
+### 1. Sending Backpropagation Data (Downstream Node)
+
+Any node can send data back to its source nodes by including a `backpropagate` field in the return value of its `compute` or `computeAsync` function:
+
+```typescript
+nodeInfo: {
+  compute: (input: any) => ({
+    result: processedValue,
+    output: processedValue,
+    backpropagate: {
+      // Any data you want to send back
+      gradient: 0.5,
+      metadata: 'custom-info'
+    }
+  })
+}
+```
+
+### 2. Receiving Backpropagation Data (Source Node)
+
+Nodes can receive backpropagation data by implementing a `backpropagate` function:
+
+```typescript
+nodeInfo: {
+  backpropagate: (data, fromNode, fromConnection) => {
+    // Update local state
+    localState.updateCount++;
+    localState.lastData = data;
+
+    // Update UI
+    updateDisplay(`Received: ${JSON.stringify(data)}`);
+  }
+}
+```
+
+### 3. Automatic Flow
+
+When a node executes and returns backpropagation data:
+1. The flow engine automatically detects the `backpropagate` field
+2. It finds the source node of the connection
+3. It calls the source node's `backpropagate` function (if defined)
+4. The source node can update its state, memory, or UI
+
+## Files Changed
+
+1. **`libs/visual-programming-system/src/utils/create-rect-node.tsx`**
+   - Extended `IComputeResult` interface with optional `backpropagate` field
+
+2. **`libs/web-flow-executor/src/types/node-info.ts`**
+   - Extended `NodeInfo` interface with optional `backpropagate` function
+
+3. **`libs/web-flow-executor/src/flow-engine/flow-engine.ts`**
+   - Added backpropagation logic for both sync and async execution
+
+4. **`libs/web-flow-executor/src/flow-engine/backpropagation.test.ts`** (new)
+   - Comprehensive unit tests with usage examples
+
+5. **`libs/web-flow-executor/src/nodes/backpropagation-example.ts`** (new)
+   - Complete example node demonstrating the feature
+
+6. **`libs/web-flow-executor/BACKPROPAGATION.md`** (new)
+   - Full documentation with examples and API reference
+
+## Key Features
+
+✅ **Opt-in**: Completely optional, existing nodes work unchanged
+✅ **Backward Compatible**: No breaking changes
+✅ **Flexible**: Can send any data structure
+✅ **Sync & Async**: Works with both `compute` and `computeAsync`
+✅ **Safe**: Gracefully handles missing implementations
+✅ **Tested**: 8 new tests, all passing
+✅ **Documented**: Complete documentation with examples
+✅ **Secure**: 0 vulnerabilities found
+
+## Use Cases
+
+1. **Neural Networks**: Send gradients back for weight updates
+2. **State Feedback**: Update source nodes with processing statistics
+3. **Memory Updates**: Store data for next execution
+4. **UI Updates**: Trigger visual changes in source nodes
+5. **Performance Monitoring**: Send timing/metrics back to sources
+
+## Example Usage
+
+```typescript
+// Input node (receives feedback)
+const inputNode = {
+  nodeInfo: {
+    compute: (input) => ({ result: input, output: input }),
+    backpropagate: (data) => {
+      console.log('Received:', data);
+      // Update state for next execution
+      memory.lastProcessingTime = data.time;
+      // Update UI
+      updateDisplay(`Last: ${data.time}ms`);
+    }
+  }
+};
+
+// Processing node (sends feedback)
+const processingNode = {
+  nodeInfo: {
+    compute: (input) => {
+      const start = Date.now();
+      const result = process(input);
+      const end = Date.now();
+
+      return {
+        result: result,
+        output: result,
+        backpropagate: {
+          time: end - start,
+          inputSize: input.length
+        }
+      };
+    }
+  }
+};
+```
+
+## Testing
+
+All tests passing:
+```
+✓ src/flow-engine/backpropagation.test.ts (8 tests) 22ms
+✓ src/nodes/json-utils/transform-json.test.ts (15 tests) 18ms
+
+Test Files  2 passed (2)
+Tests       23 passed (23)
+```
+
+## Documentation
+
+See `libs/web-flow-executor/BACKPROPAGATION.md` for:
+- Detailed implementation guide
+- Multiple usage examples
+- Complete API reference
+- Best practices
+
+## Next Steps for Users
+
+1. Read the documentation: `libs/web-flow-executor/BACKPROPAGATION.md`
+2. Check the example node: `libs/web-flow-executor/src/nodes/backpropagation-example.ts`
+3. Implement backpropagation in your own nodes as needed
+4. Use the tests as reference: `libs/web-flow-executor/src/flow-engine/backpropagation.test.ts`