vectra-client 0.4.0 → 1.0.1

data/docs/assets/style.css

@@ -4,34 +4,34 @@
 
 /* CSS Custom Properties */
 :root {
-  /* Color Palette - Clean Green Accent */
-  --tma-color-bg-primary: #0a0a0f;
-  --tma-color-bg-secondary: #111118;
-  --tma-color-bg-tertiary: #1a1a22;
-  --tma-color-bg-elevated: #222230;
-  --tma-color-bg-hover: #2a2a3a;
+  /* Color Palette - Deep Navy + Coral Accent */
+  --tma-color-bg-primary: #0c1a3f;
+  --tma-color-bg-secondary: #111f4b;
+  --tma-color-bg-tertiary: #17265c;
+  --tma-color-bg-elevated: #1f2f70;
+  --tma-color-bg-hover: #24367d;
   
-  /* Accent Colors - Based on #05df72 */
-  --tma-color-accent-primary: #05df72;
-  --tma-color-accent-light: #2ee889;
-  --tma-color-accent-dark: #04b85e;
-  --tma-color-accent-muted: rgba(5, 223, 114, 0.15);
+  /* Accent Colors - Based on logo (#e19e96) */
+  --tma-color-accent-primary: #e19e96;
+  --tma-color-accent-light: #f1b4aa;
+  --tma-color-accent-dark: #c46f63;
+  --tma-color-accent-muted: rgba(225, 158, 150, 0.16);
   
   /* Text Colors */
   --tma-color-text-primary: #f4f4f5;
-  --tma-color-text-secondary: #a1a1aa;
-  --tma-color-text-muted: #71717a;
-  --tma-color-text-accent: #05df72;
+  --tma-color-text-secondary: #c1c2d0;
+  --tma-color-text-muted: #8b8ca0;
+  --tma-color-text-accent: #e19e96;
   
   /* Border Colors */
   --tma-color-border: rgba(255, 255, 255, 0.08);
-  --tma-color-border-hover: rgba(5, 223, 114, 0.4);
+  --tma-color-border-hover: rgba(225, 158, 150, 0.6);
   
   /* Shadows */
   --tma-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
   --tma-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.5);
   --tma-shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.6);
-  --tma-shadow-glow: 0 0 30px rgba(5, 223, 114, 0.2);
+  --tma-shadow-glow: 0 0 30px rgba(225, 158, 150, 0.35);
   
   /* Typography */
   --tma-font-family-primary: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
@@ -98,7 +98,7 @@ body {
   left: 0;
   right: 0;
   height: var(--tma-header-height);
-  background: rgba(10, 10, 15, 0.95);
+  background: rgba(12, 26, 63, 0.96);
   backdrop-filter: blur(12px);
   border-bottom: 1px solid var(--tma-color-border);
   z-index: 1000;
@@ -119,15 +119,16 @@ body {
   align-items: center;
   gap: var(--tma-spacing-sm);
   text-decoration: none;
-  font-size: 1.5rem;
-  font-weight: 800;
-  color: var(--tma-color-accent-primary);
-  letter-spacing: -0.02em;
+  color: var(--tma-color-text-primary);
 }
 
 .tma-nav__brand::before {
-  content: '◆';
-  font-size: 1.2rem;
+  content: '';
+}
+
+.tma-nav__logo {
+  width: 110px;
+  display: block;
 }
 
 .tma-nav__menu {
@@ -220,7 +221,7 @@ body {
   gap: var(--tma-spacing-sm);
   padding: var(--tma-spacing-xs) var(--tma-spacing-md);
   background: var(--tma-color-accent-muted);
-  border: 1px solid rgba(5, 223, 114, 0.3);
+  border: 1px solid rgba(225, 158, 150, 0.3);
   border-radius: 100px;
   font-size: 0.85rem;
   font-weight: 500;
@@ -696,6 +697,370 @@ code {
   color: var(--tma-color-text-secondary);
 }
 
+/* Comparison Table Styles */
+.tma-comparison {
+  padding: var(--tma-spacing-3xl) var(--tma-spacing-xl);
+  max-width: var(--tma-max-width);
+  margin: 0 auto;
+}
+
+.tma-comparison-table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: var(--tma-spacing-xl) 0;
+  background: var(--tma-color-bg-secondary);
+  border-radius: var(--tma-radius-lg);
+  overflow: hidden;
+  border: 1px solid var(--tma-color-border);
+}
+
+.tma-comparison-table thead {
+  background: var(--tma-color-bg-tertiary);
+}
+
+.tma-comparison-table th {
+  padding: var(--tma-spacing-md) var(--tma-spacing-lg);
+  text-align: left;
+  font-weight: 600;
+  color: var(--tma-color-text-primary);
+  font-size: 0.9rem;
+  border-bottom: 2px solid var(--tma-color-border);
+}
+
+.tma-comparison-table th:first-child {
+  font-weight: 700;
+  color: var(--tma-color-accent-primary);
+}
+
+.tma-comparison-table td {
+  padding: var(--tma-spacing-md) var(--tma-spacing-lg);
+  border-bottom: 1px solid var(--tma-color-border);
+  color: var(--tma-color-text-secondary);
+  font-size: 0.9rem;
+}
+
+.tma-comparison-table tbody tr:hover {
+  background: var(--tma-color-bg-hover);
+}
+
+.tma-comparison-table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+.tma-comparison-table .tma-check {
+  color: var(--tma-color-accent-primary);
+  font-weight: 600;
+}
+
+.tma-comparison-table .tma-partial {
+  color: #fbbf24;
+  font-weight: 500;
+}
+
+.tma-comparison-table .tma-cross {
+  color: var(--tma-color-text-muted);
+}
+
+/* Advantages Section */
+.tma-advantages {
+  padding: var(--tma-spacing-3xl) var(--tma-spacing-xl);
+  max-width: var(--tma-max-width);
+  margin: 0 auto;
+  background: var(--tma-color-bg-secondary);
+}
+
+.tma-advantages__grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+  gap: var(--tma-spacing-lg);
+  margin-top: var(--tma-spacing-xl);
+}
+
+.tma-advantage-card {
+  padding: var(--tma-spacing-xl);
+  background: var(--tma-color-bg-tertiary);
+  border: 1px solid var(--tma-color-border);
+  border-radius: var(--tma-radius-lg);
+  border-left: 3px solid var(--tma-color-accent-primary);
+}
+
+.tma-advantage-card__title {
+  font-size: 1.1rem;
+  font-weight: 700;
+  margin-bottom: var(--tma-spacing-md);
+  color: var(--tma-color-text-primary);
+}
+
+.tma-advantage-card__list {
+  list-style: none;
+  padding: 0;
+}
+
+.tma-advantage-card__list li {
+  padding: var(--tma-spacing-xs) 0;
+  color: var(--tma-color-text-secondary);
+  font-size: 0.9rem;
+}
+
+.tma-advantage-card__list li::before {
+  content: '✓';
+  color: var(--tma-color-accent-primary);
+  font-weight: 700;
+  margin-right: var(--tma-spacing-sm);
+}
+
+/* Choose Section */
+.tma-choose {
+  padding: var(--tma-spacing-3xl) var(--tma-spacing-xl);
+  max-width: var(--tma-max-width);
+  margin: 0 auto;
+}
+
+.tma-choose__grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: var(--tma-spacing-lg);
+  margin-top: var(--tma-spacing-xl);
+}
+
+.tma-choose-card {
+  padding: var(--tma-spacing-xl);
+  background: var(--tma-color-bg-secondary);
+  border: 1px solid var(--tma-color-border);
+  border-radius: var(--tma-radius-lg);
+}
+
+.tma-choose-card__title {
+  font-size: 1.1rem;
+  font-weight: 700;
+  margin-bottom: var(--tma-spacing-md);
+  color: var(--tma-color-accent-primary);
+}
+
+.tma-choose-card__list {
+  list-style: none;
+  padding: 0;
+}
+
+.tma-choose-card__list li {
+  padding: var(--tma-spacing-xs) 0;
+  color: var(--tma-color-text-secondary);
+  font-size: 0.9rem;
+  padding-left: var(--tma-spacing-md);
+  position: relative;
+}
+
+.tma-choose-card__list li::before {
+  content: '→';
+  position: absolute;
+  left: 0;
+  color: var(--tma-color-accent-primary);
+}
+
+/* Visual Charts Section */
+.tma-charts {
+  padding: var(--tma-spacing-3xl) var(--tma-spacing-xl);
+  max-width: var(--tma-max-width);
+  margin: 0 auto;
+  background: var(--tma-color-bg-secondary);
+}
+
+.tma-charts__grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
+  gap: var(--tma-spacing-2xl);
+  margin-top: var(--tma-spacing-xl);
+}
+
+.tma-chart-card {
+  padding: var(--tma-spacing-xl);
+  background: var(--tma-color-bg-tertiary);
+  border: 1px solid var(--tma-color-border);
+  border-radius: var(--tma-radius-lg);
+}
+
+.tma-chart-card__title {
+  font-size: 1.2rem;
+  font-weight: 700;
+  margin-bottom: var(--tma-spacing-lg);
+  color: var(--tma-color-text-primary);
+  text-align: center;
+}
+
+/* Bar Chart Styles */
+.tma-bar-chart {
+  margin-top: var(--tma-spacing-lg);
+}
+
+.tma-bar-chart__item {
+  margin-bottom: var(--tma-spacing-md);
+}
+
+.tma-bar-chart__label {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: var(--tma-spacing-xs);
+  font-size: 0.9rem;
+  color: var(--tma-color-text-secondary);
+}
+
+.tma-bar-chart__name {
+  font-weight: 600;
+  color: var(--tma-color-text-primary);
+}
+
+.tma-bar-chart__value {
+  color: var(--tma-color-text-secondary);
+}
+
+.tma-bar-chart__bar-container {
+  height: 28px;
+  background: var(--tma-color-bg-primary);
+  border-radius: var(--tma-radius-sm);
+  overflow: hidden;
+  border: 1px solid var(--tma-color-border);
+}
+
+.tma-bar-chart__bar {
+  height: 100%;
+  background: linear-gradient(90deg, var(--tma-color-accent-primary), var(--tma-color-accent-light));
+  border-radius: var(--tma-radius-sm);
+  transition: width var(--tma-transition-slow);
+  display: flex;
+  align-items: center;
+  padding: 0 var(--tma-spacing-sm);
+  color: #0a0a0f;
+  font-weight: 600;
+  font-size: 0.85rem;
+  min-width: fit-content;
+}
+
+.tma-bar-chart__bar--vectra {
+  background: linear-gradient(90deg, var(--tma-color-accent-primary), var(--tma-color-accent-light));
+}
+
+.tma-bar-chart__bar--langchain {
+  background: linear-gradient(90deg, #fbbf24, #fcd34d);
+}
+
+.tma-bar-chart__bar--pgvector {
+  background: linear-gradient(90deg, #60a5fa, #93c5fd);
+}
+
+.tma-bar-chart__bar--qdrant {
+  background: linear-gradient(90deg, #a78bfa, #c4b5fd);
+}
+
+/* Radar Chart Styles */
+.tma-radar-chart {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  margin: var(--tma-spacing-xl) 0;
+}
+
+.tma-radar-chart__container {
+  position: relative;
+  width: 300px;
+  height: 300px;
+}
+
+.tma-radar-chart__svg {
+  width: 100%;
+  height: 100%;
+  transform: rotate(-90deg);
+}
+
+.tma-radar-chart__axis {
+  stroke: var(--tma-color-border);
+  stroke-width: 1;
+}
+
+.tma-radar-chart__grid {
+  stroke: var(--tma-color-border);
+  stroke-width: 0.5;
+  fill: none;
+}
+
+.tma-radar-chart__area {
+  fill: var(--tma-color-accent-muted);
+  stroke: var(--tma-color-accent-primary);
+  stroke-width: 2;
+  opacity: 0.6;
+}
+
+.tma-radar-chart__point {
+  fill: var(--tma-color-accent-primary);
+  r: 4;
+}
+
+.tma-radar-chart__label {
+  font-size: 0.75rem;
+  fill: var(--tma-color-text-secondary);
+  text-anchor: middle;
+  transform: rotate(90deg);
+}
+
+.tma-radar-chart__labels {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  flex-direction: column;
+  justify-content: space-around;
+  padding: var(--tma-spacing-md);
+  pointer-events: none;
+}
+
+.tma-radar-chart__label-item {
+  font-size: 0.8rem;
+  color: var(--tma-color-text-secondary);
+  text-align: center;
+  font-weight: 500;
+}
+
+/* Responsive Charts */
+@media (max-width: 768px) {
+  .tma-charts__grid {
+    grid-template-columns: 1fr;
+  }
+  
+  .tma-radar-chart__container {
+    width: 250px;
+    height: 250px;
+  }
+}
+
+/* Responsive Comparison Table */
+@media (max-width: 1024px) {
+  .tma-comparison-table {
+    font-size: 0.85rem;
+  }
+  
+  .tma-comparison-table th,
+  .tma-comparison-table td {
+    padding: var(--tma-spacing-sm) var(--tma-spacing-md);
+  }
+}
+
+@media (max-width: 768px) {
+  .tma-comparison-table {
+    font-size: 0.75rem;
+  }
+  
+  .tma-comparison-table th,
+  .tma-comparison-table td {
+    padding: var(--tma-spacing-xs) var(--tma-spacing-sm);
+  }
+  
+  .tma-advantages__grid,
+  .tma-choose__grid {
+    grid-template-columns: 1fr;
+  }
+}
+
 /* ============================================
    Footer
    ============================================ */

data/docs/guides/getting-started.md

@@ -121,6 +121,52 @@ if status[:error]
 end
 ```
 
+### Hybrid Search (Semantic + Keyword)
+
+Combine the best of both worlds: semantic understanding from vectors and exact keyword matching:
+
+```ruby
+# Hybrid search with 70% semantic, 30% keyword
+results = client.hybrid_search(
+  index: 'docs',
+  vector: embedding,           # Semantic search
+  text: 'ruby programming',  # Keyword search
+  alpha: 0.7,                 # 0.0 = pure keyword, 1.0 = pure semantic
+  top_k: 10
+)
+
+results.each do |match|
+  puts "#{match.id}: #{match.score}"
+end
+
+# Pure semantic (alpha = 1.0)
+results = client.hybrid_search(
+  index: 'docs',
+  vector: embedding,
+  text: 'ruby',
+  alpha: 1.0
+)
+
+# Pure keyword (alpha = 0.0)
+results = client.hybrid_search(
+  index: 'docs',
+  vector: embedding,
+  text: 'ruby programming',
+  alpha: 0.0
+)
+```
+
+**Provider Support:**
+- **Qdrant**: ✅ Full support (prefetch + rescore API)
+- **Weaviate**: ✅ Full support (hybrid GraphQL with BM25)
+- **Pinecone**: ⚠️ Partial support (requires sparse vectors for true hybrid search)
+- **pgvector**: ✅ Full support (combines vector similarity + PostgreSQL full-text search)
+
+**Note for pgvector:** Your table needs a text column with a tsvector index:
+```sql
+CREATE INDEX idx_content_fts ON my_index USING gin(to_tsvector('english', content));
+```
+
 ### Dimension Validation
 
 Vectra automatically validates that all vectors in a batch have the same dimension:
@@ -136,6 +182,21 @@ client.upsert(vectors: vectors)
 # => ValidationError: Inconsistent vector dimensions at index 1: expected 3, got 2
 ```
 
+## Rails Generator (vectra:index)
+
+For Rails apps, you can generate everything you need for a model with a single command:
+
+```bash
+rails generate vectra:index Product embedding dimension:1536 provider:qdrant
+```
+
+This will:
+
+- Create a **pgvector migration** when `provider=pgvector` (adds `embedding` vector column)
+- Generate a **model concern** (`ProductVector`) with `has_vector :embedding`
+- Update the **model** to include `ProductVector`
+- Append an entry to **`config/vectra.yml`** with index metadata (no API keys)
+
 ## Configuration
 
 Create a configuration file (Rails: `config/initializers/vectra.rb`):

data/docs/guides/performance.md

@@ -26,13 +26,47 @@ vectors = 10_000.times.map { |i| { id: "vec_#{i}", values: Array.new(384) { rand
 result = batch.upsert_async(
   index: 'my-index',
   vectors: vectors,
-  chunk_size: 100
+  chunk_size: 100,
+  on_progress: proc { |stats|
+    progress = stats[:percentage]
+    processed = stats[:processed]
+    total = stats[:total]
+    chunk = stats[:current_chunk] + 1
+    total_chunks = stats[:total_chunks]
+    
+    puts "Progress: #{progress}% (#{processed}/#{total})"
+    puts "  Chunk #{chunk}/#{total_chunks} | Success: #{stats[:success_count]}, Failed: #{stats[:failed_count]}"
+  }
 )
 
 puts "Upserted: #{result[:upserted_count]} vectors in #{result[:chunks]} chunks"
 puts "Errors: #{result[:errors].size}" if result[:errors].any?
 ```
 
+### Progress Tracking
+
+Monitor batch operations in real-time with progress callbacks:
+
+```ruby
+batch.upsert_async(
+  index: 'my-index',
+  vectors: large_vector_array,
+  chunk_size: 100,
+  on_progress: proc { |stats|
+    # stats contains:
+    # - processed: number of processed vectors
+    # - total: total number of vectors
+    # - percentage: progress percentage (0-100)
+    # - current_chunk: current chunk index (0-based)
+    # - total_chunks: total number of chunks
+    # - success_count: number of successful chunks
+    # - failed_count: number of failed chunks
+    
+    puts "Progress: #{stats[:percentage]}% (#{stats[:processed]}/#{stats[:total]})"
+  }
+)
+```
+
 ### Batch Delete
 
 ```ruby

data/docs/index.md

@@ -34,4 +34,12 @@ results = client.query(
 results.each do |match|
   puts "#{match['id']}: #{match['score']}"
 end
+
+# Hybrid search (semantic + keyword)
+results = client.hybrid_search(
+  index: 'docs',
+  vector: embedding,
+  text: 'ruby programming',
+  alpha: 0.7  # 70% semantic, 30% keyword
+)
 ```

data/docs/providers/pgvector.md

@@ -43,6 +43,7 @@ client = Vectra::Client.new(
 - ✅ ACID transactions
 - ✅ Complex queries
 - ✅ Rails ActiveRecord integration
+- ✅ Hybrid search (vector + full-text search)
 
 ## Example
 
@@ -63,6 +64,17 @@ client.upsert(
 
 # Search using cosine distance
 results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
+
+# Hybrid search (requires text column with tsvector index)
+# First, create the index:
+# CREATE INDEX idx_content_fts ON my_index USING gin(to_tsvector('english', content));
+results = client.hybrid_search(
+  index: 'my_index',
+  vector: embedding,
+  text: 'ruby programming',
+  alpha: 0.7,
+  text_column: 'content'  # default: 'content'
+)
 ```
 
 ## ActiveRecord Integration

data/docs/providers/pinecone.md

@@ -32,6 +32,7 @@ client = Vectra::Client.new(
 - ✅ Index statistics
 - ✅ Metadata filtering
 - ✅ Namespace support
+- ⚠️ Hybrid search (partial - requires sparse vectors)
 
 ## Example
 
@@ -56,6 +57,15 @@ results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
 results.matches.each do |match|
   puts "#{match['id']}: #{match['score']}"
 end
+
+# Hybrid search (note: requires sparse vectors for true hybrid search)
+# For now, this uses dense vector search only
+results = client.hybrid_search(
+  index: 'my-index',
+  vector: embedding,
+  text: 'ruby programming',
+  alpha: 0.7
+)
 ```
 
 ## Configuration Options

data/docs/providers/qdrant.md

@@ -56,6 +56,14 @@ client.upsert(
 
 # Search
 results = client.query(vector: [0.1, 0.2, 0.3], top_k: 10)
+
+# Hybrid search (semantic + keyword)
+results = client.hybrid_search(
+  index: 'my-collection',
+  vector: embedding,
+  text: 'ruby programming',
+  alpha: 0.7  # 70% semantic, 30% keyword
+)
 ```
 
 ## Configuration Options

data/docs/providers/weaviate.md

@@ -47,6 +47,7 @@ client = Vectra::Client.new(
 - ✅ Delete by IDs or filter
 - ✅ List and describe classes
 - ✅ Basic stats via GraphQL `Aggregate`
+- ✅ Hybrid search (BM25 + vector similarity)
 
 ## Basic Example
 
@@ -89,6 +90,15 @@ results = client.query(
 results.each do |match|
   puts "#{match.id} (score=#{match.score.round(3)}): #{match.metadata["title"]}"
 end
+
+# Hybrid search (BM25 + vector)
+results = client.hybrid_search(
+  index: index,
+  vector: embedding,
+  text: 'ruby programming',
+  alpha: 0.7,  # 70% semantic, 30% keyword
+  top_k: 10
+)
 ```
 
 ## Advanced Filtering

data/examples/README.md

@@ -29,6 +29,24 @@ psql vectra_demo -c "CREATE EXTENSION vector;"
 
 ## Examples
 
+### Rails Quickstart (with generator)
+
+```bash
+# Generate Vectra index for Product model
+rails generate vectra:index Product embedding dimension:1536 provider:qdrant
+
+# Run migrations (if pgvector)
+rails db:migrate
+```
+
+Then in `app/models/product.rb`:
+
+```ruby
+class Product < ApplicationRecord
+  include ProductVector  # generated concern with has_vector :embedding
+end
+```
+
 ### 1. **Comprehensive Demo** (`comprehensive_demo.rb`)
 
 **⭐ START HERE** - Complete production-ready demonstration of all Vectra features.