vectra-client 1.0.6 → 1.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aada098f943da3a1b81288f46e32382e775492efc96e87a175b1e9ba002ea7c3
-  data.tar.gz: 24f2efb3bdf110541c60ce4710f61e616fc824bf4874d8205ff5d1ebdaa8d9bc
+  metadata.gz: '05778206f66d4e2ead830f5b7c5885f6336b46d36af696f3df5a56eb26163c5f'
+  data.tar.gz: 1ae5814cd10df006ecf5568f34e457400b072ecc8a06dbf85a4e4f5b94120fb9
 SHA512:
-  metadata.gz: 00df0da772c575e7933c97b640e0e6c1f31a5cdd7671b9f41106ccc54eda2b0f7e90871dd7ddbfe654ff9007fb5cc0b3a4897a0955284e0b4625c3dd1ddf9d3c
-  data.tar.gz: d16d6c0425c8ba8ecad38021f416220c91a01bd4f58d8b0d397324dead8e9e3d32bc46b90583ac7678ecc2e0b2dcb0084dfad3b99fd021577c5c469ab07e8588
+  metadata.gz: d25889a4626c9caa9edf7ccc285c849799de87cf38a8a7a6f56a49edb46da592b28bc0232960e2612fd0d9199e990c21bd5fe6b88f15351d8ff38c73bd7afc84
+  data.tar.gz: d4ef355089814ed4caf8c61e216b9554f23035df12be72a65c778b3230bd2a32f16ecf4c50de3bc33e40dc323f1aee83d7a891ad962bec105585c8bc6b30902b

data/CHANGELOG.md

@@ -1,14 +1,17 @@
 # Changelog
 
+## [v1.0.8](https://github.com/stokry/vectra/tree/v1.0.8) (2026-01-14)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.0.7...v1.0.8)
+
+## [v1.0.7](https://github.com/stokry/vectra/tree/v1.0.7) (2026-01-14)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.0.6...v1.0.7)
+
 ## [v1.0.6](https://github.com/stokry/vectra/tree/v1.0.6) (2026-01-13)
 
 [Full Changelog](https://github.com/stokry/vectra/compare/v1.0.5...v1.0.6)
 
-### Improvements
-- Refined test suite and documentation
-- Performance optimizations
-- Enhanced stability and reliability
-
 ## [v1.0.5](https://github.com/stokry/vectra/tree/v1.0.5) (2026-01-13)
 
 [Full Changelog](https://github.com/stokry/vectra/compare/v1.0.4...v1.0.5)

data/README.md

@@ -229,6 +229,19 @@ For a complete step-by-step guide including:
 
 👉 **[Read the complete Rails Integration Guide](https://vectra-docs.netlify.app/guides/rails-integration/)**
 
+### Recipes & Patterns
+
+Real-world patterns for common use cases:
+
+- **E-Commerce Search** - Semantic product search with filters
+- **Blog Hybrid Search** - Combine semantic + keyword matching
+- **Multi-Tenant SaaS** - Namespace isolation per tenant
+- **RAG Chatbot** - Context retrieval for LLMs
+- **Zero-Downtime Migration** - Switch providers safely
+- **Recommendation Engine** - Find similar items
+
+👉 **[Browse all Recipes & Patterns](https://vectra-docs.netlify.app/guides/recipes/)**
+
 ## Production Patterns
 
 Vectra includes 7 production-ready patterns out of the box:

data/docs/_layouts/default.html

@@ -40,6 +40,7 @@
       </button>
       <ul class="tma-nav__menu" id="nav-menu">
         <li><a href="{{ site.baseurl }}/guides/getting-started" class="tma-nav__link">Getting Started</a></li>
+        <li><a href="{{ site.baseurl }}/guides/recipes" class="tma-nav__link">Recipes</a></li>
         <li><a href="{{ site.baseurl }}/providers" class="tma-nav__link">Providers</a></li>
         <li><a href="{{ site.baseurl }}/api/overview" class="tma-nav__link">API</a></li>
         <li><a href="{{ site.baseurl }}/examples" class="tma-nav__link">Examples</a></li>

data/docs/_layouts/home.html

@@ -40,6 +40,7 @@
       </button>
       <ul class="tma-nav__menu" id="nav-menu">
         <li><a href="{{ site.baseurl }}/guides/getting-started" class="tma-nav__link">Getting Started</a></li>
+        <li><a href="{{ site.baseurl }}/guides/recipes" class="tma-nav__link">Recipes</a></li>
         <li><a href="{{ site.baseurl }}/providers" class="tma-nav__link">Providers</a></li>
         <li><a href="{{ site.baseurl }}/api/overview" class="tma-nav__link">API</a></li>
         <li><a href="{{ site.baseurl }}/examples" class="tma-nav__link">Examples</a></li>
@@ -568,6 +569,50 @@
     </div>
   </section>
 
+  <!-- Recipes Section -->
+  <section class="tma-recipes">
+    <div class="tma-section-header">
+      <h2 class="tma-section-header__title">Recipes & Patterns</h2>
+      <p class="tma-section-header__subtitle">Real-world patterns for common use cases</p>
+    </div>
+    
+    <div class="tma-recipes__grid">
+      <a href="{{ site.baseurl }}/guides/recipes/#e-commerce-semantic-product-search-with-filters" class="tma-recipe-card">
+        <h3 class="tma-recipe-card__title">🛒 E-Commerce Search</h3>
+        <p class="tma-recipe-card__description">Semantic product search with filters for category, price, and availability</p>
+      </a>
+      
+      <a href="{{ site.baseurl }}/guides/recipes/#blog-hybrid-search-semantic--keyword" class="tma-recipe-card">
+        <h3 class="tma-recipe-card__title">📝 Blog Hybrid Search</h3>
+        <p class="tma-recipe-card__description">Combine semantic understanding with exact keyword matching</p>
+      </a>
+      
+      <a href="{{ site.baseurl }}/guides/recipes/#multi-tenant-saas-namespace-isolation" class="tma-recipe-card">
+        <h3 class="tma-recipe-card__title">🏢 Multi-Tenant SaaS</h3>
+        <p class="tma-recipe-card__description">Namespace isolation per tenant with a single index</p>
+      </a>
+      
+      <a href="{{ site.baseurl }}/guides/recipes/#rag-chatbot-context-retrieval" class="tma-recipe-card">
+        <h3 class="tma-recipe-card__title">🤖 RAG Chatbot</h3>
+        <p class="tma-recipe-card__description">Retrieve relevant context chunks for LLM integration</p>
+      </a>
+      
+      <a href="{{ site.baseurl }}/guides/recipes/#zero-downtime-provider-migration" class="tma-recipe-card">
+        <h3 class="tma-recipe-card__title">🔄 Provider Migration</h3>
+        <p class="tma-recipe-card__description">Zero-downtime migration between providers</p>
+      </a>
+      
+      <a href="{{ site.baseurl }}/guides/recipes/#recommendation-engine-similar-items" class="tma-recipe-card">
+        <h3 class="tma-recipe-card__title">💡 Recommendations</h3>
+        <p class="tma-recipe-card__description">Find similar items based on user behavior</p>
+      </a>
+    </div>
+    
+    <div style="text-align: center; margin-top: var(--tma-spacing-lg);">
+      <a href="{{ site.baseurl }}/guides/recipes" class="tma-btn tma-btn--secondary">View All Recipes →</a>
+    </div>
+  </section>
+
   <!-- Quick Start Code Section -->
   <section class="tma-code-section">
     <div class="tma-section-header">

data/docs/_layouts/page.html

@@ -40,6 +40,7 @@
       </button>
       <ul class="tma-nav__menu" id="nav-menu">
         <li><a href="{{ site.baseurl }}/guides/getting-started" class="tma-nav__link">Getting Started</a></li>
+        <li><a href="{{ site.baseurl }}/guides/recipes" class="tma-nav__link">Recipes</a></li>
         <li><a href="{{ site.baseurl }}/providers" class="tma-nav__link">Providers</a></li>
         <li><a href="{{ site.baseurl }}/api/overview" class="tma-nav__link">API</a></li>
         <li><a href="{{ site.baseurl }}/examples" class="tma-nav__link">Examples</a></li>

data/docs/api/cheatsheet.md

@@ -0,0 +1,387 @@
+---
+layout: page
+title: API Cheatsheet
+permalink: /api/cheatsheet/
+---
+
+# API Cheatsheet
+
+Quick reference for the most important Vectra APIs.
+
+> For full details, see the [API Overview](/api/overview/) and provider guides.
+
+## Core Client
+
+### Initialize Client
+
+```ruby
+require 'vectra'
+
+client = Vectra::Client.new(
+  provider: :qdrant,          # :pinecone, :qdrant, :weaviate, :pgvector, :memory
+  api_key:  ENV['QDRANT_API_KEY'],
+  host:     'http://localhost:6333',
+  environment: 'us-west-4'   # For Pinecone
+)
+```
+
+Or use shortcuts:
+
+```ruby
+client = Vectra.qdrant(host: 'http://localhost:6333')
+client = Vectra.pinecone(api_key: ENV['PINECONE_API_KEY'], environment: 'us-west-4')
+client = Vectra.pgvector(connection_url: ENV['DATABASE_URL'])
+client = Vectra.memory # In-memory (testing only)
+```
+
+You can also set a **default index and namespace**:
+
+```ruby
+client = Vectra::Client.new(
+  provider: :qdrant,
+  host: 'http://localhost:6333',
+  index: 'products',
+  namespace: 'tenant-1'
+)
+
+# Now index and namespace can be omitted
+client.upsert(vectors: [...])
+client.query(vector: query_embedding, top_k: 10)
+```
+
+### Upsert
+
+```ruby
+client.upsert(
+  index: 'documents',
+  vectors: [
+    {
+      id: 'doc-1',
+      values: embedding_array,
+      metadata: { title: 'Hello World', category: 'docs' }
+    }
+  ],
+  namespace: 'default' # optional
+)
+```
+
+### Query (similarity search)
+
+```ruby
+results = client.query(
+  index: 'documents',
+  vector: query_embedding,
+  top_k: 10,
+  filter: { category: 'docs' },
+  namespace: 'default',
+  include_values: false,
+  include_metadata: true
+)
+
+results.each do |match|
+  puts "#{match.id} (score=#{match.score.round(3)}): #{match.metadata['title']}"
+end
+```
+
+### Hybrid Search (semantic + keyword)
+
+```ruby
+results = client.hybrid_search(
+  index: 'documents',
+  vector: query_embedding,
+  text: 'ruby vector search',
+  alpha: 0.7,            # 70% semantic, 30% keyword
+  top_k: 10,
+  filter: { category: 'blog' }
+)
+```
+
+Supported providers: Qdrant ✅, Weaviate ✅, pgvector ✅, Pinecone ⚠️
+
+### Fetch
+
+```ruby
+vectors = client.fetch(
+  index: 'documents',
+  ids: ['doc-1', 'doc-2'],
+  namespace: 'default'
+)
+
+vectors['doc-1'].values   # => [0.1, 0.2, ...]
+vectors['doc-1'].metadata # => { 'title' => 'Hello World' }
+```
+
+### Update
+
+```ruby
+client.update(
+  index: 'documents',
+  id: 'doc-1',
+  metadata: { category: 'guides' }
+)
+```
+
+### Delete
+
+```ruby
+# By IDs
+client.delete(index: 'documents', ids: ['doc-1', 'doc-2'])
+
+# By filter
+client.delete(index: 'documents', filter: { category: 'old' })
+
+# Delete all in namespace
+client.delete(index: 'documents', delete_all: true)
+```
+
+### Index Management
+
+```ruby
+# Create index
+client.create_index(name: 'documents', dimension: 384, metric: 'cosine')
+
+# List indexes
+indexes = client.list_indexes
+# => [{ name: 'documents', dimension: 384, ... }]
+
+# Describe index
+info = client.describe_index(index: 'documents')
+# => { name: 'documents', dimension: 384, metric: 'cosine', status: 'ready' }
+
+# Get stats
+stats = client.stats(index: 'documents')
+# => { total_vector_count: 1000, dimension: 384, namespaces: { ... } }
+
+# List namespaces
+namespaces = client.list_namespaces(index: 'documents')
+# => ['tenant-1', 'tenant-2']
+
+# Delete index
+client.delete_index(name: 'old-index')
+```
+
+**Note:** `create_index` and `delete_index` are supported by Pinecone, Qdrant, and pgvector. Memory and Weaviate providers don't support these operations.
+
+---
+
+## Health & Monitoring
+
+### Health Check
+
+```ruby
+if client.healthy?
+  puts 'Vectra provider is healthy'
+else
+  puts 'Vectra provider is NOT healthy'
+end
+```
+
+### Ping (with latency)
+
+```ruby
+status = client.ping
+# => { healthy: true, provider: :qdrant, latency_ms: 23.4 }
+
+puts "Provider: #{status[:provider]}, latency: #{status[:latency_ms]}ms"
+```
+
+### Rails Health Endpoint (Example)
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  get '/health/vectra', to: 'health#vectra'
+end
+```
+
+```ruby
+# app/controllers/health_controller.rb
+class HealthController < ApplicationController
+  def vectra
+    client = Vectra::Client.new
+
+    status = client.ping
+    if status[:healthy]
+      render json: { status: 'ok', provider: status[:provider], latency_ms: status[:latency_ms] }
+    else
+      render json: { status: 'unhealthy' }, status: :service_unavailable
+    end
+  rescue => e
+    render json: { status: 'error', error: e.message }, status: :service_unavailable
+  end
+end
+```
+
+Use this endpoint for Kubernetes / load balancer health checks.
+
+---
+
+## Vector Helpers
+
+### Normalize Embeddings
+
+```ruby
+embedding  = openai_response['data'][0]['embedding']
+normalized = Vectra::Vector.normalize(embedding, type: :l2) # or :l1
+
+client.upsert(
+  index: 'documents',
+  vectors: [
+    { id: 'doc-1', values: normalized, metadata: { title: 'Hello' } }
+  ]
+)
+```
+
+### In-Place Normalization
+
+```ruby
+vector = Vectra::Vector.new(id: 'doc-1', values: embedding)
+vector.normalize! # Mutates values
+client.upsert(index: 'documents', vectors: [vector])
+```
+
+### Embedding Cache Helper
+
+```ruby
+cache = Vectra::Cache.new(ttl: 600, max_size: 1000)
+
+embedding = Vectra::Embeddings.fetch(
+  cache: cache,
+  model_name: "Product",
+  id: product.id,
+  input: product.description,
+  field: :description
+) do
+  EmbeddingService.generate(product.description)
+end
+```
+
+---
+
+## Batch Operations
+
+### Simple Batch Upsert
+
+```ruby
+vectors = products.map do |product|
+  {
+    id: product.id.to_s,
+    values: product.embedding,
+    metadata: { name: product.name, price: product.price }
+  }
+end
+
+client.upsert(index: 'products', vectors: vectors)
+```
+
+### Batch with Progress Callback
+
+```ruby
+Vectra::Batch.upsert(
+  client: client,
+  index: 'products',
+  vectors: vectors,
+  batch_size: 100,
+  on_progress: ->(batch_index, total_batches, batch_count) do
+    puts "Batch #{batch_index + 1}/#{total_batches} (#{batch_count} vectors)"
+  end
+)
+```
+
+### Batch Query (Multiple Vectors)
+
+```ruby
+batch = Vectra::Batch.new(client, concurrency: 4)
+
+# Find similar items for multiple products at once
+product_embeddings = products.map(&:embedding)
+results = batch.query_async(
+  index: 'products',
+  vectors: product_embeddings,
+  top_k: 5
+)
+
+# Each result corresponds to one product
+results.each_with_index do |result, i|
+  puts "Similar to product #{i}: #{result.ids}"
+end
+```
+
+---
+
+## ActiveRecord + has_vector DSL
+
+### Basic Setup
+
+```ruby
+class Document < ApplicationRecord
+  include Vectra::ActiveRecord
+
+  has_vector :embedding,
+    provider: :qdrant,
+    index: 'documents',
+    dimension: 1536,
+    metadata_fields: [:title, :category]
+end
+```
+
+### Auto-Index on Save
+
+```ruby
+doc = Document.create!(
+  title: 'Hello World',
+  category: 'docs',
+  embedding: EmbeddingService.generate('Hello World')
+)
+```
+
+### Vector Search from Model
+
+```ruby
+results = Document.vector_search(
+  embedding: EmbeddingService.generate('vector search in ruby'),
+  limit: 10,
+  filter: { category: 'docs' }
+)
+
+results.each do |doc|
+  puts doc.title
+end
+```
+
+### Reindex All Records
+
+```ruby
+# Reindex all documents that already have embeddings
+processed = Document.reindex_vectors(
+  scope: Document.where.not(embedding: nil),
+  batch_size: 500
+)
+
+puts "Reindexed #{processed} documents"
+```
+
+---
+
+## Error Handling
+
+```ruby
+begin
+  client.query(index: 'missing', vector: [0.1, 0.2, 0.3])
+rescue Vectra::NotFoundError => e
+  Rails.logger.warn("Index not found: #{e.message}")
+rescue Vectra::RateLimitError => e
+  Rails.logger.error("Rate limited: #{e.message}")
+rescue Vectra::Error => e
+  Rails.logger.error("Vectra error: #{e.message}")
+end
+```
+
+---
+
+## See Also
+
+- [API Overview](/api/overview/)
+- [Recipes & Patterns](/guides/recipes/)
+- [Rails Integration Guide](/guides/rails-integration/)
+- [Memory Provider (Testing)](/providers/memory/)