Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
2026-02-28 14:39:40 -05:00
commit d803bfe2b1
7854 changed files with 3522914 additions and 0 deletions
--- a/crates/ruvector-postgres/docs/GNN_INDEX.md
+++ b/crates/ruvector-postgres/docs/GNN_INDEX.md
@@ -0,0 +1,222 @@
+# GNN Module Index
+
+## Overview
+
+Complete Graph Neural Network (GNN) implementation for ruvector-postgres PostgreSQL extension.
+
+**Total Lines of Code**: 1,301  
+**Total Documentation**: 1,156 lines  
+**Implementation Status**: ✅ Complete
+
+## Source Files
+
+### Core Implementation (src/gnn/)
+
+| File | Lines | Description |
+|------|-------|-------------|
+| **mod.rs** | 30 | Module exports and organization |
+| **message_passing.rs** | 233 | Message passing framework, adjacency lists, propagation |
+| **aggregators.rs** | 197 | Sum/mean/max aggregation functions |
+| **gcn.rs** | 227 | Graph Convolutional Network layer |
+| **graphsage.rs** | 300 | GraphSAGE with neighbor sampling |
+| **operators.rs** | 314 | PostgreSQL operator functions |
+| **Total** | **1,301** | Complete GNN implementation |
+
+## Documentation Files
+
+### User Documentation (docs/)
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| **GNN_IMPLEMENTATION_SUMMARY.md** | 280 | Architecture overview and design decisions |
+| **GNN_QUICK_REFERENCE.md** | 368 | SQL function reference and common patterns |
+| **GNN_USAGE_EXAMPLES.md** | 508 | Real-world examples and applications |
+| **Total** | **1,156** | Comprehensive documentation |
+
+## Key Features
+
+### Implemented Components
+
+✅ **Message Passing Framework**
+- Generic MessagePassing trait
+- build_adjacency_list() for graph structure
+- propagate() for message passing
+- propagate_weighted() for edge weights
+- Parallel node processing with Rayon
+
+✅ **Aggregation Functions**
+- Sum aggregation
+- Mean aggregation
+- Max aggregation (element-wise)
+- Weighted aggregation
+- Generic aggregate() function
+
+✅ **GCN Layer**
+- Xavier/Glorot weight initialization
+- Degree normalization
+- Linear transformation
+- ReLU activation
+- Optional bias terms
+- Edge weight support
+
+✅ **GraphSAGE Layer**
+- Uniform neighbor sampling
+- Multiple aggregator types (Mean, MaxPool, LSTM)
+- Separate neighbor/self weight matrices
+- L2 normalization
+- Inductive learning support
+
+✅ **PostgreSQL Operators**
+- ruvector_gcn_forward()
+- ruvector_gnn_aggregate()
+- ruvector_message_pass()
+- ruvector_graphsage_forward()
+- ruvector_gnn_batch_forward()
+
+## Testing Coverage
+
+### Unit Tests
+- ✅ Message passing correctness
+- ✅ All aggregation methods
+- ✅ GCN layer forward pass
+- ✅ GraphSAGE sampling
+- ✅ Edge cases (disconnected nodes, empty graphs)
+
+### PostgreSQL Tests (#[pg_test])
+- ✅ SQL function correctness
+- ✅ Empty input handling
+- ✅ Weighted edges
+- ✅ Batch processing
+- ✅ Different aggregation methods
+
+## SQL Functions Reference
+
+### 1. GCN Forward Pass
+```sql
+ruvector_gcn_forward(embeddings, src, dst, weights, out_dim) -> FLOAT[][]
+```
+
+### 2. GNN Aggregation
+```sql
+ruvector_gnn_aggregate(messages, method) -> FLOAT[]
+```
+
+### 3. GraphSAGE Forward Pass
+```sql
+ruvector_graphsage_forward(embeddings, src, dst, out_dim, num_samples) -> FLOAT[][]
+```
+
+### 4. Multi-Hop Message Passing
+```sql
+ruvector_message_pass(node_table, edge_table, embedding_col, hops, layer_type) -> TEXT
+```
+
+### 5. Batch Processing
+```sql
+ruvector_gnn_batch_forward(embeddings_batch, edge_indices, graph_sizes, layer_type, out_dim) -> FLOAT[][]
+```
+
+## Usage Examples
+
+### Basic GCN
+```sql
+SELECT ruvector_gcn_forward(
+    ARRAY[ARRAY[1.0, 2.0], ARRAY[3.0, 4.0]],
+    ARRAY[0], ARRAY[1], NULL, 8
+);
+```
+
+### Aggregation
+```sql
+SELECT ruvector_gnn_aggregate(
+    ARRAY[ARRAY[1.0, 2.0], ARRAY[3.0, 4.0]],
+    'mean'
+);
+```
+
+### GraphSAGE with Sampling
+```sql
+SELECT ruvector_graphsage_forward(
+    node_embeddings, edge_src, edge_dst, 64, 10
+);
+```
+
+## Performance Characteristics
+
+- **Parallel Processing**: All nodes processed concurrently via Rayon
+- **Memory Efficient**: HashMap-based adjacency lists for sparse graphs
+- **Scalable Sampling**: GraphSAGE samples k neighbors instead of processing all
+- **Batch Support**: Process multiple graphs simultaneously
+- **Zero-Copy**: Minimal data copying during operations
+
+## Integration
+
+The GNN module is integrated into the main extension via:
+
+```rust
+// src/lib.rs
+pub mod gnn;
+```
+
+All functions are automatically registered with PostgreSQL via pgrx macros.
+
+## Dependencies
+
+- `pgrx` - PostgreSQL extension framework
+- `rayon` - Parallel processing
+- `rand` - Random neighbor sampling
+- `serde_json` - JSON serialization
+
+## Documentation Structure
+
+```
+docs/
+├── GNN_INDEX.md                    # This file - index of all GNN files
+├── GNN_IMPLEMENTATION_SUMMARY.md   # Architecture and design
+├── GNN_QUICK_REFERENCE.md          # SQL function reference
+└── GNN_USAGE_EXAMPLES.md           # Real-world examples
+```
+
+## Source Code Structure
+
+```
+src/gnn/
+├── mod.rs                # Module exports
+├── message_passing.rs    # Core framework
+├── aggregators.rs        # Aggregation functions
+├── gcn.rs               # GCN layer
+├── graphsage.rs         # GraphSAGE layer
+└── operators.rs         # PostgreSQL functions
+```
+
+## Next Steps
+
+To use the GNN module:
+
+1. **Install Extension**:
+   ```sql
+   CREATE EXTENSION ruvector;
+   ```
+
+2. **Check Functions**:
+   ```sql
+   \df ruvector_gnn_*
+   \df ruvector_gcn_*
+   \df ruvector_graphsage_*
+   ```
+
+3. **Run Examples**:
+   See [GNN_USAGE_EXAMPLES.md](./GNN_USAGE_EXAMPLES.md)
+
+## References
+
+- [Implementation Summary](./GNN_IMPLEMENTATION_SUMMARY.md) - Architecture details
+- [Quick Reference](./GNN_QUICK_REFERENCE.md) - Function reference
+- [Usage Examples](./GNN_USAGE_EXAMPLES.md) - Real-world applications
+- [Integration Plan](../integration-plans/03-gnn-layers.md) - Original specification
+
+---
+
+**Status**: ✅ Implementation Complete  
+**Last Updated**: 2025-12-02  
+**Version**: 1.0.0