Package Exports

@ruvector/postgres-cli
@ruvector/postgres-cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ruvector/postgres-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@ruvector/postgres-cli

The most advanced AI vector database CLI for PostgreSQL. A drop-in pgvector replacement with 53+ SQL functions, 39 attention mechanisms, GNN layers, hyperbolic embeddings, and self-learning capabilities.

Why RuVector?

Feature	pgvector	RuVector
Vector Search	HNSW, IVFFlat	HNSW, IVFFlat
Distance Metrics	3	8+ (including hyperbolic)
Attention Mechanisms	-	39 types
Graph Neural Networks	-	GCN, GraphSAGE, GAT
Hyperbolic Embeddings	-	Poincare, Lorentz
Sparse Vectors / BM25	-	Full support
Self-Learning	-	ReasoningBank
Agent Routing	-	Tiny Dancer

Installation

# Global installation
npm install -g @ruvector/postgres-cli

# Or use npx directly
npx @ruvector/postgres-cli info

Quick Start

1. Connect to PostgreSQL

# Set connection string
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"

# Or use -c flag
ruvector-pg -c "postgresql://user:pass@localhost:5432/mydb" info

2. Install Extension

# Install ruvector extension
ruvector-pg install

# Verify installation
ruvector-pg info

3. Create & Search Vectors

# Create a vector table with HNSW index
ruvector-pg vector create embeddings --dim 384 --index hnsw

# Insert vectors from file
ruvector-pg vector insert embeddings --file vectors.json

# Search similar vectors
ruvector-pg vector search embeddings --query "[0.1, 0.2, 0.3, ...]" --top-k 10

# Compute distance between vectors
ruvector-pg vector distance --a "[0.1, 0.2]" --b "[0.3, 0.4]" --metric cosine

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    @ruvector/postgres-cli                          │
├─────────────────────────────────────────────────────────────────────┤
│  CLI Layer (Commander.js)                                          │
│    ├── vector    - CRUD & search operations                        │
│    ├── attention - 39 attention mechanism types                    │
│    ├── gnn       - Graph Neural Network layers                     │
│    ├── graph     - Cypher queries & traversal                      │
│    ├── hyperbolic- Poincare/Lorentz embeddings                     │
│    ├── sparse    - BM25/SPLADE scoring                             │
│    ├── routing   - Tiny Dancer agent routing                       │
│    ├── learning  - ReasoningBank self-learning                     │
│    ├── bench     - Performance benchmarking                        │
│    └── quant     - Quantization (scalar/product/binary)            │
├─────────────────────────────────────────────────────────────────────┤
│  Client Layer (pg with connection pooling)                         │
│    ├── Connection pooling (max 10, idle timeout 30s)               │
│    ├── Automatic retry (3 attempts, exponential backoff)           │
│    ├── Batch operations (1000 vectors/batch)                       │
│    ├── SQL injection protection                                    │
│    └── Input validation                                            │
├─────────────────────────────────────────────────────────────────────┤
│  PostgreSQL Extension (ruvector-postgres crate)                    │
│    └── 53 SQL functions exposed via pgrx                           │
└─────────────────────────────────────────────────────────────────────┘

Commands Reference

Vector Operations

# Create table with HNSW or IVFFlat index
ruvector-pg vector create <table> --dim <n> --index <hnsw|ivfflat>

# Insert from JSON file
ruvector-pg vector insert <table> --file data.json

# Semantic search
ruvector-pg vector search <table> --query "[...]" --top-k 10 --metric cosine

# Distance calculation
ruvector-pg vector distance --a "[...]" --b "[...]" --metric <cosine|l2|ip>

# Vector normalization
ruvector-pg vector normalize --vector "[0.5, 0.3, 0.2]"

Hyperbolic Geometry

Perfect for hierarchical data like taxonomies and knowledge graphs:

# Poincare ball distance
ruvector-pg hyperbolic poincare-distance --a "[0.1, 0.2]" --b "[0.3, 0.4]" --curvature -1.0

# Lorentz hyperboloid distance
ruvector-pg hyperbolic lorentz-distance --a "[1.1, 0.1, 0.2]" --b "[1.2, 0.3, 0.4]"

# Mobius addition (hyperbolic translation)
ruvector-pg hyperbolic mobius-add --a "[0.1, 0.2]" --b "[0.05, 0.1]"

# Exponential map (tangent to manifold)
ruvector-pg hyperbolic exp-map --base "[0.0, 0.0]" --tangent "[0.1, 0.2]"

# Convert between models
ruvector-pg hyperbolic poincare-to-lorentz --vector "[0.3, 0.4]"
ruvector-pg hyperbolic lorentz-to-poincare --vector "[1.5, 0.3, 0.4]"

Attention Mechanisms

# Compute attention (39 types available)
ruvector-pg attention compute \
  --query "[0.1, 0.2, ...]" \
  --keys "[[...], [...]]" \
  --values "[[...], [...]]" \
  --type scaled_dot

# List all 39 attention types
ruvector-pg attention list-types

Graph Neural Networks

# GCN layer
ruvector-pg gnn gcn --features "[[...]]" --adj "[[...]]" --weights "[[...]]"

# GraphSAGE layer
ruvector-pg gnn graphsage --features "[[...]]" --neighbors "[[...]]"

# GAT (Graph Attention) layer
ruvector-pg gnn gat --features "[[...]]" --adj "[[...]]"

Graph & Cypher

# Execute Cypher query
ruvector-pg graph query "MATCH (n:Person)-[:KNOWS]->(m) RETURN n, m"

# Create nodes and edges
ruvector-pg graph create-node --labels "Person,Developer" --properties '{"name": "Alice"}'
ruvector-pg graph create-edge --from node1 --to node2 --type KNOWS

# Graph traversal
ruvector-pg graph traverse --start node123 --depth 3 --type bfs

Sparse Vectors & BM25

# Create sparse vector
ruvector-pg sparse create --indices "[0, 5, 10]" --values "[0.5, 0.3, 0.2]" --dim 100

# BM25 scoring
ruvector-pg sparse bm25 --query-terms "[1, 5, 10]" --doc-freqs "[100, 50, 10]"

# Sparse dot product
ruvector-pg sparse dot --a "0:0.5,5:0.3" --b "0:0.2,5:0.8"

Agent Routing (Tiny Dancer)

# Route query to best agent
ruvector-pg routing route --query "[0.1, 0.2, ...]" --agents agents.json

# Register new agent
ruvector-pg routing register --name "summarizer" --capabilities "[0.8, 0.2, ...]"

# Multi-agent routing
ruvector-pg routing multi-route --query "[...]" --top-k 3

Self-Learning (ReasoningBank)

# Record learning trajectory
ruvector-pg learning record --input "[...]" --output "[...]" --success true

# Get adaptive search parameters
ruvector-pg learning adaptive-search --context "[0.1, 0.2, ...]"

# Train from trajectories
ruvector-pg learning train --file trajectories.json --epochs 10

Benchmarking

# Run full benchmark suite
ruvector-pg bench run --type all --size 10000 --dim 384

# Benchmark specific operation
ruvector-pg bench run --type search --size 100000 --dim 768

# Generate report
ruvector-pg bench report --format table

Benchmarks

Performance measured on AMD EPYC 7763 (64 cores), 256GB RAM:

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
Poincare Distance	0.02ms	0.02ms	0.02ms
GCN Forward	2.1ms	18ms	180ms
BM25 Score	0.05ms	0.08ms	0.15ms

Dimensions: 384 for vector ops, 128 for GNN

Docker Quick Start

# Pull and run the RuVector PostgreSQL image
docker run -d --name ruvector-pg \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  ruvector/postgres:latest

# Connect with CLI
ruvector-pg -c "postgresql://postgres:secret@localhost:5432/postgres" install

Usage Tutorial: Building a Semantic Search Engine

Step 1: Setup

# Create database
createdb semantic_search
ruvector-pg -c "postgresql://localhost/semantic_search" install

Step 2: Create Embeddings Table

ruvector-pg vector create documents --dim 384 --index hnsw

Step 3: Insert Documents (from JSON)

// documents.json
[
  {"vector": [0.1, 0.2, ...], "metadata": {"title": "AI Overview", "category": "tech"}},
  {"vector": [0.3, 0.1, ...], "metadata": {"title": "ML Basics", "category": "tech"}}
]

ruvector-pg vector insert documents --file documents.json

Step 4: Semantic Search

# Find similar documents
ruvector-pg vector search documents \
  --query "[0.15, 0.18, ...]" \
  --top-k 5 \
  --metric cosine

Step 5: Add Hybrid Search with BM25

# Create sparse representation for text search
ruvector-pg sparse create --indices "[10, 25, 42]" --values "[2.5, 1.8, 3.2]" --dim 10000

Environment Variables

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	`postgresql://localhost:5432/ruvector`
`RUVECTOR_POOL_SIZE`	Connection pool size	`10`
`RUVECTOR_TIMEOUT`	Query timeout (ms)	`30000`
`RUVECTOR_RETRIES`	Max retry attempts	`3`

Global Options

-c, --connection <string>  PostgreSQL connection string
-v, --verbose              Enable verbose output
-h, --help                 Display help
--version                  Display version

Features Summary

Vector Search: HNSW and IVFFlat indexes with cosine, L2, inner product, and hyperbolic metrics
39 Attention Mechanisms: Scaled dot-product, multi-head, flash, sparse, linear, causal, and more
Graph Neural Networks: GCN, GraphSAGE, GAT, GIN layers with message passing
Graph Operations: Full Cypher query support, BFS/DFS traversal, PageRank
Self-Learning: ReasoningBank-based trajectory learning and adaptive search
Hyperbolic Embeddings: Poincare ball and Lorentz hyperboloid models for hierarchies
Sparse Vectors: BM25, TF-IDF, and SPLADE for hybrid search
Agent Routing: Tiny Dancer routing with FastGRNN acceleration
Quantization: Scalar, product, and binary quantization for memory efficiency
Performance: Connection pooling, batch operations, automatic retries

ruvector-postgres - Rust PostgreSQL extension
ruvector-core - Core vector operations library

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT - see LICENSE