From 3d3e5cd64847f0ba9304ecdfdfed7ffa4a4fdcff Mon Sep 17 00:00:00 2001 From: rUv Date: Sat, 6 Dec 2025 19:17:02 +0000 Subject: [PATCH] docs(postgres): Add Docker Hub README with tutorials and feature comparison MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Improved overview with clear value proposition - Feature comparison table (pgvector vs RuVector) - 4 tutorials: semantic search, hybrid search, knowledge graphs, agent routing - Performance benchmarks and environment variables - Links to related packages 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- crates/ruvector-postgres/DOCKERHUB.md | 217 ++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 crates/ruvector-postgres/DOCKERHUB.md diff --git a/crates/ruvector-postgres/DOCKERHUB.md b/crates/ruvector-postgres/DOCKERHUB.md new file mode 100644 index 00000000..e9e3b797 --- /dev/null +++ b/crates/ruvector-postgres/DOCKERHUB.md @@ -0,0 +1,217 @@ +# RuVector-Postgres + +**The most advanced PostgreSQL vector database extension.** A high-performance, drop-in replacement for pgvector with 53+ SQL functions, SIMD acceleration, 39 attention mechanisms, Graph Neural Networks, hyperbolic embeddings, and self-learning capabilities. + +## 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