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/DOCKERHUB.md
+++ b/crates/ruvector-postgres/DOCKERHUB.md
@@ -0,0 +1,224 @@
+# RuVector-Postgres
+
+**The most advanced PostgreSQL vector database extension.** A high-performance, drop-in replacement for pgvector with 77+ SQL functions, SIMD acceleration, 39 attention mechanisms, Graph Neural Networks, hyperbolic embeddings, and self-learning capabilities.
+
+## v2.0.0 (December 2025)
+
+- **IVFFlat Index**: Full inverted list storage with proper page management
+- **HNSW Index**: Fixed query execution with heap scan integration
+- **Security Audit**: 3 critical SQL injection vulnerabilities fixed
+- **Multi-tenant**: Validated tenant isolation with parameterized queries
+
+## Quick Start
+
+```bash
+# Start RuVector-Postgres
+docker run -d --name ruvector \
+  -e POSTGRES_PASSWORD=secret \
+  -p 5432:5432 \
+  ruvnet/ruvector-postgres:latest
+
+# Connect and use
+psql -h localhost -U ruvector -d ruvector_test
+
+# Create extension
+CREATE EXTENSION ruvector;
+```
+
+## Why RuVector vs pgvector?
+
+| Feature | pgvector | RuVector-Postgres |
+|---------|----------|-------------------|
+| **Vector Search** | HNSW, IVFFlat | HNSW, IVFFlat (optimized) |
+| **Distance Metrics** | 3 | **8+** (including hyperbolic) |
+| **Attention Mechanisms** | None | **39 types** (scaled-dot, multi-head, flash, sparse) |
+| **Graph Neural Networks** | None | **GCN, GraphSAGE, GAT** |
+| **Hyperbolic Embeddings** | None | **Poincare, Lorentz** (for hierarchies) |
+| **Sparse Vectors** | Partial | **Full support + BM25** |
+| **Self-Learning** | None | **ReasoningBank** (adaptive search) |
+| **Agent Routing** | None | **Tiny Dancer** (11 functions) |
+| **Graph/Cypher** | None | **Full support** |
+| **SIMD Acceleration** | Partial | **Full AVX-512/NEON** |
+| **Quantization** | None | **Scalar, Product, Binary** |
+
+## Features
+
+### Core Vector Operations
+- L2, Cosine, Inner Product, Manhattan distances
+- Vector normalization, addition, scalar multiplication
+- SIMD-accelerated (AVX2/AVX-512/NEON)
+
+### Hyperbolic Embeddings
+Perfect for hierarchical data (taxonomies, org charts, knowledge graphs):
+```sql
+SELECT ruvector_poincare_distance(a, b, -1.0);
+SELECT ruvector_mobius_add(a, b, -1.0);
+```
+
+### Sparse Vectors & BM25
+Full sparse vector support with text scoring:
+```sql
+SELECT ruvector_sparse_dot(a, b);
+SELECT ruvector_bm25_score(query, doc_freqs, doc_len, avg_len, total);
+```
+
+### 39 Attention Mechanisms
+Transformer-style attention in PostgreSQL:
+```sql
+SELECT ruvector_attention_scaled_dot(query, keys, values);
+SELECT ruvector_attention_multi_head(query, keys, values, 8);
+```
+
+### Graph Neural Networks
+GNN inference directly in PostgreSQL:
+```sql
+SELECT ruvector_gnn_gcn_layer(features, adjacency, weights);
+SELECT ruvector_gnn_graphsage_layer(features, neighbors, weights);
+```
+
+### Self-Learning (ReasoningBank)
+Adaptive search parameter optimization:
+```sql
+SELECT ruvector_record_trajectory(input, output, success, context);
+SELECT ruvector_adaptive_search(query, context, ef_search);
+```
+
+## Tutorial 1: Semantic Search
+
+```sql
+-- Create extension
+CREATE EXTENSION ruvector;
+
+-- Create table with vector column
+CREATE TABLE documents (
+    id SERIAL PRIMARY KEY,
+    content TEXT,
+    embedding ruvector(1536)
+);
+
+-- Insert some documents (embeddings from your ML model)
+INSERT INTO documents (content, embedding) VALUES
+    ('PostgreSQL is a powerful database', '[0.1, 0.2, ...]'),
+    ('Vector search enables AI applications', '[0.3, 0.1, ...]');
+
+-- Create HNSW index for fast search
+CREATE INDEX ON documents USING ruhnsw (embedding ruvector_l2_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- Search for similar documents
+SELECT content, embedding <-> $query_embedding AS distance
+FROM documents
+ORDER BY distance
+LIMIT 10;
+```
+
+## Tutorial 2: Hybrid Search (Vector + BM25)
+
+```sql
+-- Combine vector similarity with text scoring
+SELECT
+    content,
+    0.7 * (1.0 / (1.0 + embedding <-> $query_vector)) +
+    0.3 * ruvector_bm25_score(terms, doc_freqs, length, avg_len, total) AS score
+FROM documents
+ORDER BY score DESC
+LIMIT 10;
+```
+
+## Tutorial 3: Knowledge Graph with Hyperbolic Embeddings
+
+```sql
+-- Hyperbolic embeddings preserve hierarchy better than Euclidean
+-- Perfect for taxonomies, org charts, knowledge graphs
+
+-- Create taxonomy table
+CREATE TABLE taxonomy_nodes (
+    id SERIAL PRIMARY KEY,
+    name TEXT,
+    parent_id INTEGER,
+    embedding ruvector(128)  -- Poincare embeddings
+);
+
+-- Find similar nodes using hyperbolic distance
+SELECT name, ruvector_poincare_distance(embedding, $query, -1.0) AS distance
+FROM taxonomy_nodes
+ORDER BY distance
+LIMIT 10;
+```
+
+## Tutorial 4: Multi-Agent Query Routing
+
+```sql
+-- Register AI agents with their capabilities
+SELECT ruvector_register_agent('code_expert', ARRAY['coding', 'debugging'], $embedding);
+SELECT ruvector_register_agent('math_expert', ARRAY['math', 'statistics'], $embedding);
+
+-- Route user query to best agent
+SELECT ruvector_route_query($user_query_embedding,
+    (SELECT array_agg(row(name, capabilities)) FROM agents)
+) AS best_agent;
+```
+
+## Distance Operators
+
+| Operator | Distance | Use Case |
+|----------|----------|----------|
+| `<->` | L2 (Euclidean) | General similarity |
+| `<=>` | Cosine | Text embeddings |
+| `<#>` | Inner Product | Normalized vectors |
+| `<+>` | Manhattan (L1) | Sparse features |
+
+## Index Types
+
+### HNSW (Hierarchical Navigable Small World)
+```sql
+CREATE INDEX ON items USING ruhnsw (embedding ruvector_l2_ops)
+WITH (m = 16, ef_construction = 64);
+
+SET ruvector.ef_search = 100;  -- Tune search quality
+```
+
+### IVFFlat
+```sql
+CREATE INDEX ON items USING ruivfflat (embedding ruvector_l2_ops)
+WITH (lists = 100);
+
+SET ruvector.ivfflat_probes = 10;
+```
+
+## Performance
+
+| Operation | 10K vectors | 100K vectors | 1M vectors |
+|-----------|-------------|--------------|------------|
+| HNSW Build | 0.8s | 8.2s | 95s |
+| HNSW Search (top-10) | 0.3ms | 0.5ms | 1.2ms |
+| Cosine Distance | 0.01ms | 0.01ms | 0.01ms |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `POSTGRES_USER` | ruvector | Database user |
+| `POSTGRES_PASSWORD` | ruvector | Database password |
+| `POSTGRES_DB` | ruvector_test | Default database |
+
+## CLI Tool
+
+```bash
+npm install -g @ruvector/postgres-cli
+
+ruvector-pg install --method docker
+ruvector-pg vector create table --dim 384 --index hnsw
+ruvector-pg bench run --type all --size 10000
+```
+
+## Links
+
+- [GitHub](https://github.com/ruvnet/ruvector)
+- [npm CLI](https://www.npmjs.com/package/@ruvector/postgres-cli)
+- [crates.io](https://crates.io/crates/ruvector-postgres)
+- [Documentation](https://docs.rs/ruvector-postgres)
+
+## License
+
+MIT License