vectra-client 1.0.4 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f6f5038173b0fbcde02bcfe548c2a7b34bcef702233151f811cdceaff451cb0
-  data.tar.gz: 3b5557a28941df944df56379e6f657da4f027942bd34ee94fd8adea9ec93ce03
+  metadata.gz: aada098f943da3a1b81288f46e32382e775492efc96e87a175b1e9ba002ea7c3
+  data.tar.gz: 24f2efb3bdf110541c60ce4710f61e616fc824bf4874d8205ff5d1ebdaa8d9bc
 SHA512:
-  metadata.gz: d4ff59a890b201c2877d496a77106f926fb641e126c6e68501d7e516e2d28d433685ca9cba490e8fee29e7d4846ca36cf962564ea9be7db75b925d344d957864
-  data.tar.gz: 42f0b9c6be55e599ed3342254f379df8065ce2a0e13f235d0678a10c309b924a59705c8c7e7b3d50682b116891d1ca25edc36e9f0ee5cddb258c0d2c98404af4
+  metadata.gz: 00df0da772c575e7933c97b640e0e6c1f31a5cdd7671b9f41106ccc54eda2b0f7e90871dd7ddbfe654ff9007fb5cc0b3a4897a0955284e0b4625c3dd1ddf9d3c
+  data.tar.gz: d16d6c0425c8ba8ecad38021f416220c91a01bd4f58d8b0d397324dead8e9e3d32bc46b90583ac7678ecc2e0b2dcb0084dfad3b99fd021577c5c469ab07e8588

data/CHANGELOG.md

@@ -1,10 +1,19 @@
 # Changelog
 
-## [v1.0.4](https://github.com/stokry/vectra/tree/v1.0.4) (2026-01-13)
+## [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
 
-### Added
-- Comprehensive Rails generator test coverage
-- Support for all vector database providers in generator
+## [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)
+
+## [v1.0.4](https://github.com/stokry/vectra/tree/v1.0.4) (2026-01-13)
 
 [Full Changelog](https://github.com/stokry/vectra/compare/v1.0.3...v1.0.4)
 

data/README.md

@@ -184,6 +184,8 @@ graph TB
 
 ## Rails Integration
 
+### Quick Start
+
 ```ruby
 class Document < ApplicationRecord
   include Vectra::ActiveRecord
@@ -216,6 +218,17 @@ This will:
 - **Update the model** to include `ProductVector`
 - **Append to `config/vectra.yml`** with index metadata (no API keys)
 
+### Complete Rails Guide
+
+For a complete step-by-step guide including:
+- Setting up embeddings (OpenAI, Cohere)
+- Processing 1000+ products
+- Background jobs
+- Hybrid search
+- Performance optimization
+
+👉 **[Read the complete Rails Integration Guide](https://vectra-docs.netlify.app/guides/rails-integration/)**
+
 ## Production Patterns
 
 Vectra includes 7 production-ready patterns out of the box:

data/docs/guides/getting-started.md

@@ -197,6 +197,18 @@ This will:
 - Update the **model** to include `ProductVector`
 - Append an entry to **`config/vectra.yml`** with index metadata (no API keys)
 
+### Complete Rails Integration Guide
+
+For a comprehensive Rails guide including:
+- Step-by-step setup
+- Embedding generation (OpenAI, Cohere)
+- Processing 1000+ products with batch operations
+- Background jobs for async processing
+- Hybrid search examples
+- Performance optimization tips
+
+👉 **[Read the complete Rails Integration Guide]({{ site.baseurl }}/guides/rails-integration/)**
+
 ## Configuration
 
 Create a configuration file (Rails: `config/initializers/vectra.rb`):
@@ -214,6 +226,7 @@ client = Vectra::Client.new
 
 ## Next Steps
 
+- **[Rails Integration Guide]({{ site.baseurl }}/guides/rails-integration/)** - Complete step-by-step guide for Rails apps
 - [API Reference]({{ site.baseurl }}/api/overview)
 - [Provider Guides]({{ site.baseurl }}/providers)
 - [Examples]({{ site.baseurl }}/examples/basic-usage)

data/docs/guides/rails-integration.md

@@ -0,0 +1,690 @@
+---
+layout: page
+title: Rails Integration Guide
+permalink: /guides/rails-integration/
+---
+
+# Rails Integration Guide
+
+Complete step-by-step guide to integrate Vectra into your Rails application with vector search capabilities.
+
+## Overview
+
+This guide will walk you through:
+1. Installing Vectra in a Rails app
+2. Setting up a Product model with vector search
+3. Generating embeddings for 1000 products
+4. Performing vector searches
+5. Using all Vectra features
+
+## Step 1: Installation
+
+### Add Vectra to your Gemfile
+
+```ruby
+# Gemfile
+gem 'vectra-client'
+```
+
+```bash
+bundle install
+```
+
+### Run the Install Generator
+
+```bash
+rails generate vectra:install
+```
+
+This creates:
+- `config/initializers/vectra.rb` - Configuration file
+- `db/migrate/XXXXXX_enable_pgvector_extension.rb` - pgvector extension (if using pgvector)
+
+## Step 2: Configure Vectra
+
+**Important:** Always add `require 'vectra'` at the top of your initializer to ensure all Providers are loaded in Rails autoloading context.
+
+### Option A: Using pgvector (PostgreSQL)
+
+```ruby
+# config/initializers/vectra.rb
+require 'vectra'  # Ensure all Providers are loaded
+
+Vectra.configure do |config|
+  config.provider = :pgvector
+  config.host = Rails.application.config.database_configuration[Rails.env]['database']
+  # Or use connection URL:
+  # config.host = ENV['DATABASE_URL']
+end
+```
+
+### Option B: Using Qdrant
+
+```ruby
+# config/initializers/vectra.rb
+require 'vectra'  # Ensure all Providers are loaded
+
+Vectra.configure do |config|
+  config.provider = :qdrant
+  config.host = ENV.fetch('QDRANT_HOST', 'http://localhost:6333')
+  config.api_key = ENV['QDRANT_API_KEY'] # Optional for local instances
+end
+```
+
+### Option C: Using Pinecone
+
+```ruby
+# config/initializers/vectra.rb
+require 'vectra'  # Ensure all Providers are loaded
+
+Vectra.configure do |config|
+  config.provider = :pinecone
+  config.api_key = ENV['PINECONE_API_KEY']
+  config.environment = ENV['PINECONE_ENVIRONMENT'] # e.g., 'us-west-4'
+end
+```
+
+## Step 3: Create Product Model with Vector Search
+
+### Generate the Model and Migration
+
+```bash
+rails generate model Product name:string description:text price:decimal category:string
+rails generate vectra:index Product embedding dimension:1536 provider:qdrant
+```
+
+This will:
+- Create a migration for the `embedding` column (if `provider=pgvector`)
+- Generate `app/models/concerns/product_vector.rb` with `has_vector` configuration
+- Update `app/models/product.rb` to include the concern
+- Add configuration to `config/vectra.yml`
+
+### Run Migrations
+
+```bash
+rails db:migrate
+```
+
+### Manual Setup (Alternative)
+
+If you prefer manual setup:
+
+```ruby
+# db/migrate/XXXXXX_create_products.rb
+class CreateProducts < ActiveRecord::Migration[7.0]
+  def change
+    create_table :products do |t|
+      t.string :name
+      t.text :description
+      t.decimal :price
+      t.string :category
+      # For pgvector, add vector column:
+      # t.column :embedding, :vector, limit: 1536
+      t.timestamps
+    end
+  end
+end
+```
+
+```ruby
+# app/models/concerns/product_vector.rb
+module ProductVector
+  extend ActiveSupport::Concern
+
+  included do
+    include Vectra::ActiveRecord
+
+    has_vector :embedding,
+               provider: :qdrant,
+               index: 'products',
+               dimension: 1536,
+               auto_index: true,
+               metadata_fields: [:name, :category, :price]
+  end
+end
+```
+
+```ruby
+# app/models/product.rb
+class Product < ApplicationRecord
+  include ProductVector
+
+  # Generate embedding before validation
+  before_validation :generate_embedding, if: -> { description.present? && embedding.nil? }
+
+  private
+
+  def generate_embedding
+    # Use OpenAI, Cohere, or any embedding service
+    self.embedding = generate_embedding_from_text(description)
+  end
+
+  def generate_embedding_from_text(text)
+    # Example with OpenAI (install 'ruby-openai' gem)
+    # client = OpenAI::Client.new(access_token: ENV['OPENAI_API_KEY'])
+    # response = client.embeddings(
+    #   parameters: {
+    #     model: 'text-embedding-3-small',
+    #     input: text
+    #   }
+    # )
+    # response.dig('data', 0, 'embedding')
+    
+    # For demo purposes, use a simple hash-based embedding
+    # In production, use a real embedding service!
+    hash = text.hash.abs
+    Array.new(1536) { |i| ((hash * (i + 1)) % 1000) / 1000.0 }
+  end
+end
+```
+
+## Step 4: Generate Embeddings for Products
+
+### Using OpenAI (Recommended)
+
+First, add the OpenAI gem:
+
+```ruby
+# Gemfile
+gem 'ruby-openai'
+```
+
+```bash
+bundle install
+```
+
+Then create a service:
+
+```ruby
+# app/services/embedding_service.rb
+class EmbeddingService
+  def self.generate(text)
+    client = OpenAI::Client.new(access_token: ENV['OPENAI_API_KEY'])
+    response = client.embeddings(
+      parameters: {
+        model: 'text-embedding-3-small', # 1536 dimensions
+        input: text
+      }
+    )
+    
+    embedding = response.dig('data', 0, 'embedding')
+    Vectra::Vector.normalize(embedding) # Normalize for better cosine similarity
+  end
+end
+```
+
+Update your Product model:
+
+```ruby
+# app/models/product.rb
+class Product < ApplicationRecord
+  include ProductVector
+
+  before_validation :generate_embedding, if: -> { description.present? && embedding.nil? }
+
+  private
+
+  def generate_embedding
+    self.embedding = EmbeddingService.generate(description)
+  end
+end
+```
+
+### Using Cohere
+
+```ruby
+# Gemfile
+gem 'cohere-rb'
+```
+
+```ruby
+# app/services/embedding_service.rb
+class EmbeddingService
+  def self.generate(text)
+    client = Cohere::Client.new(api_key: ENV['COHERE_API_KEY'])
+    response = client.embed(
+      texts: [text],
+      model: 'embed-english-v3.0',
+      input_type: 'search_document'
+    )
+    
+    embedding = response.dig('embeddings', 0)
+    Vectra::Vector.normalize(embedding)
+  end
+end
+```
+
+### Batch Processing for 1000 Products
+
+Create a rake task to process all products:
+
+```ruby
+# lib/tasks/vectra.rake
+namespace :vectra do
+  desc "Generate embeddings for all products without embeddings"
+  task generate_embeddings: :environment do
+    products = Product.where(embedding: nil).where.not(description: nil)
+    total = products.count
+    
+    puts "Generating embeddings for #{total} products..."
+    
+    products.find_each.with_index do |product, index|
+      begin
+        product.generate_embedding!
+        product.save!
+        
+        if (index + 1) % 100 == 0
+          puts "Processed #{index + 1}/#{total} products..."
+        end
+      rescue => e
+        puts "Error processing product #{product.id}: #{e.message}"
+      end
+    end
+    
+    puts "✅ Completed! Generated embeddings for #{Product.where.not(embedding: nil).count} products"
+  end
+  
+  desc "Re-index all products in vector database"
+  task reindex: :environment do
+    products = Product.where.not(embedding: nil)
+    total = products.count
+    
+    puts "Re-indexing #{total} products..."
+    
+    products.find_each.with_index do |product, index|
+      begin
+        product.index_vector!
+        
+        if (index + 1) % 100 == 0
+          puts "Indexed #{index + 1}/#{total} products..."
+        end
+      rescue => e
+        puts "Error indexing product #{product.id}: #{e.message}"
+      end
+    end
+    
+    puts "✅ Completed! Re-indexed #{total} products"
+  end
+end
+```
+
+Run the task:
+
+```bash
+rails vectra:generate_embeddings
+```
+
+## Step 5: Create the Vector Index
+
+### For Qdrant/Pinecone/Weaviate
+
+```ruby
+# rails console
+client = Vectra::Client.new
+client.provider.create_index(
+  name: 'products',
+  dimension: 1536,
+  metric: 'cosine'
+)
+```
+
+### For pgvector
+
+The index is created automatically via migration, but you can also create it manually:
+
+```ruby
+# db/migrate/XXXXXX_add_vector_index_to_products.rb
+class AddVectorIndexToProducts < ActiveRecord::Migration[7.0]
+  def change
+    add_index :products, :embedding, 
+              using: :ivfflat, 
+              with: { lists: 100 },
+              opclass: :vector_cosine_ops
+  end
+end
+```
+
+## Step 6: Using Vector Search
+
+### Basic Search
+
+```ruby
+# In your controller or service
+class ProductsController < ApplicationController
+  def search
+    query_text = params[:query]
+    
+    # Generate embedding for search query
+    query_embedding = EmbeddingService.generate(query_text)
+    
+    # Search for similar products
+    results = Product.vector_search(query_embedding, limit: 10)
+    
+    render json: results.map { |p| 
+      { 
+        id: p.id, 
+        name: p.name, 
+        score: p.vector_score,
+        price: p.price 
+      } 
+    }
+  end
+end
+```
+
+### Search with Metadata Filters
+
+```ruby
+# Search only in specific category
+results = Product.vector_search(
+  query_embedding,
+  limit: 10,
+  filter: { category: 'electronics' }
+)
+
+# Search with price range (if using Qdrant/Weaviate)
+results = Product.vector_search(
+  query_embedding,
+  limit: 10,
+  filter: { 
+    category: 'electronics',
+    price: { gte: 100, lte: 500 }
+  }
+)
+```
+
+### Hybrid Search (Semantic + Keyword)
+
+```ruby
+# Search combining semantic similarity and keyword matching
+query_embedding = EmbeddingService.generate(params[:query])
+
+results = Product.vectra_client.hybrid_search(
+  index: 'products',
+  vector: query_embedding,
+  text: params[:query],
+  alpha: 0.7, # 70% semantic, 30% keyword
+  top_k: 10
+)
+
+# Convert results to Product objects
+product_ids = results.map(&:id)
+products = Product.where(id: product_ids).index_by(&:id)
+results_with_products = results.map do |result|
+  product = products[result.id]
+  product&.vector_score = result.score
+  product
+end.compact
+```
+
+### Find Similar Products
+
+```ruby
+# Find products similar to a specific product
+product = Product.find(params[:id])
+similar = Product.similar_to(product, limit: 5)
+
+similar.each do |p|
+  puts "#{p.name} (similarity: #{p.vector_score})"
+end
+```
+
+## Step 7: Advanced Features
+
+### Background Job for Embedding Generation
+
+```ruby
+# app/jobs/generate_embedding_job.rb
+class GenerateEmbeddingJob < ApplicationJob
+  queue_as :default
+
+  def perform(product_id)
+    product = Product.find(product_id)
+    return if product.embedding.present?
+    
+    product.generate_embedding!
+    product.save!
+  end
+end
+```
+
+```ruby
+# app/models/product.rb
+class Product < ApplicationRecord
+  include ProductVector
+
+  after_create :enqueue_embedding_generation, if: -> { description.present? }
+
+  private
+
+  def enqueue_embedding_generation
+    GenerateEmbeddingJob.perform_later(id)
+  end
+end
+```
+
+### Batch Upsert for Performance
+
+```ruby
+# app/services/product_indexer.rb
+class ProductIndexer
+  def self.batch_index(products)
+    vectors = products.map do |product|
+      {
+        id: product.id.to_s,
+        values: product.embedding,
+        metadata: {
+          name: product.name,
+          category: product.category,
+          price: product.price.to_f
+        }
+      }
+    end
+    
+    client = Vectra::Client.new
+    client.upsert(
+      index: 'products',
+      vectors: vectors
+    )
+  end
+end
+
+# Usage
+products = Product.where.not(embedding: nil).limit(100)
+ProductIndexer.batch_index(products)
+```
+
+### Using Callbacks for Progress Tracking
+
+```ruby
+# Batch upsert with progress callback
+client = Vectra::Client.new
+
+client.upsert(
+  index: 'products',
+  vectors: vectors,
+  on_progress: ->(progress) {
+    puts "Progress: #{progress[:processed]}/#{progress[:total]} (#{progress[:percentage]}%)"
+  }
+)
+```
+
+## Step 8: Complete Example: Products Controller
+
+```ruby
+# app/controllers/products_controller.rb
+class ProductsController < ApplicationController
+  def index
+    @products = Product.all.page(params[:page])
+  end
+
+  def show
+    @product = Product.find(params[:id])
+    @similar = Product.similar_to(@product, limit: 4)
+  end
+
+  def search
+    query = params[:q]
+    return render json: [] if query.blank?
+    
+    # Generate embedding for query
+    query_embedding = EmbeddingService.generate(query)
+    
+    # Vector search
+    results = Product.vector_search(
+      query_embedding,
+      limit: 20,
+      filter: params[:category].present? ? { category: params[:category] } : nil
+    )
+    
+    render json: {
+      query: query,
+      results: results.map { |p|
+        {
+          id: p.id,
+          name: p.name,
+          description: p.description,
+          price: p.price,
+          category: p.category,
+          similarity_score: p.vector_score.round(4)
+        }
+      }
+    }
+  end
+
+  def create
+    @product = Product.new(product_params)
+    
+    if @product.save
+      # Embedding is generated automatically via before_validation
+      # and indexed automatically via after_save (auto_index: true)
+      render json: @product, status: :created
+    else
+      render json: @product.errors, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def product_params
+    params.require(:product).permit(:name, :description, :price, :category)
+  end
+end
+```
+
+## Step 9: Testing
+
+```ruby
+# spec/models/product_spec.rb
+RSpec.describe Product, type: :model do
+  describe 'vector search' do
+    let!(:product1) do
+      Product.create!(
+        name: 'Laptop',
+        description: 'High-performance laptop for developers',
+        price: 1299.99,
+        category: 'electronics',
+        embedding: Array.new(1536) { rand }
+      )
+    end
+
+    let!(:product2) do
+      Product.create!(
+        name: 'Desktop PC',
+        description: 'Powerful desktop computer for gaming',
+        price: 1999.99,
+        category: 'electronics',
+        embedding: Array.new(1536) { rand }
+      )
+    end
+
+    it 'finds similar products' do
+      query_vector = product1.embedding
+      results = Product.vector_search(query_vector, limit: 5)
+      
+      expect(results).to include(product1)
+      expect(results.first.vector_score).to be > 0
+    end
+
+    it 'filters by category' do
+      query_vector = product1.embedding
+      results = Product.vector_search(
+        query_vector,
+        limit: 10,
+        filter: { category: 'electronics' }
+      )
+      
+      expect(results.all? { |p| p.category == 'electronics' }).to be true
+    end
+  end
+end
+```
+
+## Step 10: Performance Tips
+
+### 1. Use Connection Pooling (pgvector)
+
+```ruby
+# config/initializers/vectra.rb
+Vectra.configure do |config|
+  config.provider = :pgvector
+  config.pool_size = 10 # Connection pool size
+end
+```
+
+### 2. Enable Caching
+
+```ruby
+# config/initializers/vectra.rb
+Vectra.configure do |config|
+  config.cache_enabled = true
+  config.cache_ttl = 3600 # 1 hour
+end
+```
+
+### 3. Batch Operations
+
+Always use batch operations when processing multiple products:
+
+```ruby
+# Good: Batch upsert
+Product.where.not(embedding: nil).find_in_batches(batch_size: 100) do |batch|
+  vectors = batch.map { |p| { id: p.id.to_s, values: p.embedding } }
+  Vectra::Client.new.upsert(index: 'products', vectors: vectors)
+end
+
+# Bad: Individual upserts
+Product.where.not(embedding: nil).each do |product|
+  Vectra::Client.new.upsert(
+    index: 'products',
+    vectors: [{ id: product.id.to_s, values: product.embedding }]
+  )
+end
+```
+
+## Summary
+
+You now have a complete Rails application with:
+- ✅ Vector search for products
+- ✅ Automatic embedding generation
+- ✅ Automatic indexing on save
+- ✅ Search with metadata filters
+- ✅ Hybrid search (semantic + keyword)
+- ✅ Batch processing for 1000+ products
+- ✅ Background jobs for async processing
+
+## Troubleshooting
+
+If you encounter issues like `uninitialized constant Vectra::Providers::Qdrant`, see the [Rails Troubleshooting Guide]({{ site.baseurl }}/guides/rails-troubleshooting/) for solutions.
+
+Common fixes:
+- Add `require 'vectra'` at the top of your initializer
+- Restart Rails server after configuration changes
+- Check that all Providers are loaded: `Vectra::Providers.constants`
+
+## Next Steps
+
+- [Rails Troubleshooting Guide]({{ site.baseurl }}/guides/rails-troubleshooting/) - Common issues and solutions
+- [API Reference]({{ site.baseurl }}/api/overview)
+- [Provider Guides]({{ site.baseurl }}/providers)
+- [Performance Optimization]({{ site.baseurl }}/guides/performance)

data/docs/guides/rails-troubleshooting.md

@@ -0,0 +1,377 @@
+---
+layout: page
+title: Rails Troubleshooting
+permalink: /guides/rails-troubleshooting/
+---
+
+# Rails Troubleshooting Guide
+
+## Common Issues and Solutions
+
+### Issue: `uninitialized constant Vectra::Providers::Qdrant`
+
+**Error Message:**
+```
+NameError: uninitialized constant Vectra::Providers::Qdrant
+```
+
+**Cause:**
+In Rails, when using autoloading (Zeitwerk), modules are loaded on-demand. If `Vectra::Client` is instantiated before all Providers are loaded, you'll get this error.
+
+**Solution 1: Explicit require in initializer (Recommended)**
+
+Add `require 'vectra'` at the top of your initializer:
+
+```ruby
+# config/initializers/vectra.rb
+require 'vectra'  # Ensure all Providers are loaded
+
+Vectra.configure do |config|
+  config.provider = :qdrant
+  # ... rest of config
+end
+```
+
+**Solution 2: Lazy loading in ActiveRecord**
+
+If you're using `has_vector` in your models, the client is created lazily, which should work. However, if you're creating clients directly, ensure Providers are loaded:
+
+```ruby
+# This will work because vectra.rb loads all Providers
+client = Vectra::Client.new(provider: :qdrant)
+
+# But if you're in a context where autoloading hasn't kicked in:
+require 'vectra'  # Load everything first
+client = Vectra::Client.new(provider: :qdrant)
+```
+
+**Solution 3: Check autoload paths**
+
+If you're using Zeitwerk, ensure Vectra is in your autoload paths:
+
+```ruby
+# config/application.rb
+config.autoload_paths << Rails.root.join('lib')
+```
+
+However, since Vectra is a gem, this shouldn't be necessary. The gem's `lib` directory should be in the load path automatically.
+
+### Issue: `uninitialized constant Vectra::Client::HealthCheck`
+
+**Error Message:**
+```
+NameError: uninitialized constant Vectra::Client::HealthCheck
+```
+
+**Cause:**
+Module loading order issue. `Client` tries to include `HealthCheck` before it's loaded.
+
+**Solution:**
+
+This is already fixed in the gem with defensive requires. If you still see this, ensure you're using the latest version:
+
+```ruby
+# In your Gemfile
+gem 'vectra-client', '>= 1.0.1'
+```
+
+Then run:
+```bash
+bundle update vectra-client
+```
+
+### Issue: Providers not found in Rails console
+
+**Symptom:**
+```ruby
+# In rails console
+Vectra::Providers::Qdrant
+# => NameError: uninitialized constant Vectra::Providers::Qdrant
+```
+
+**Solution:**
+
+Load Vectra explicitly:
+```ruby
+require 'vectra'
+Vectra::Providers::Qdrant
+# => Vectra::Providers::Qdrant
+```
+
+Or use the client directly:
+```ruby
+client = Vectra::Client.new(provider: :qdrant)
+# This will load all necessary Providers
+```
+
+### Issue: Autoloading conflicts with Zeitwerk
+
+**Symptom:**
+In Rails 7+ with Zeitwerk, you might see warnings or errors about constant loading.
+
+**Solution:**
+
+Vectra uses explicit `require_relative` statements, which work with both classic autoloading and Zeitwerk. However, if you're seeing issues:
+
+1. **Ensure initializer loads Vectra:**
+   ```ruby
+   # config/initializers/vectra.rb
+   require 'vectra'  # Explicit require
+   ```
+
+2. **Disable Zeitwerk for Vectra (not recommended, but works):**
+   ```ruby
+   # config/application.rb
+   config.autoloader = :classic  # Only if absolutely necessary
+   ```
+
+3. **Use eager loading in production:**
+   ```ruby
+   # config/environments/production.rb
+   config.eager_load = true  # Already default in production
+   ```
+
+### Issue: `has_vector` not working in models
+
+**Symptom:**
+```ruby
+class Product < ApplicationRecord
+  include Vectra::ActiveRecord
+  has_vector :embedding, dimension: 1536
+end
+
+# Error: undefined method `has_vector`
+```
+
+**Cause:**
+`Vectra::ActiveRecord` module not loaded or included incorrectly.
+
+**Solution:**
+
+1. **Ensure Vectra is required:**
+   ```ruby
+   # config/initializers/vectra.rb
+   require 'vectra'
+   ```
+
+2. **Check include order:**
+   ```ruby
+   class Product < ApplicationRecord
+     include Vectra::ActiveRecord  # Must be included first
+     
+     has_vector :embedding, dimension: 1536, provider: :qdrant
+   end
+   ```
+
+3. **Use the generator (recommended):**
+   ```bash
+   rails generate vectra:index Product embedding dimension:1536 provider:qdrant
+   ```
+   This will create the concern correctly.
+
+### Issue: Client created but provider methods fail
+
+**Symptom:**
+```ruby
+client = Vectra::Client.new(provider: :qdrant)
+client.upsert(...)  # Works
+client.query(...)   # NameError: uninitialized constant Vectra::Providers::Qdrant
+```
+
+**Cause:**
+Provider was loaded initially, but then unloaded by autoloader, or there's a circular dependency.
+
+**Solution:**
+
+1. **Use explicit require:**
+   ```ruby
+   require 'vectra'
+   client = Vectra::Client.new(provider: :qdrant)
+   ```
+
+2. **Check for circular dependencies:**
+   If you have custom code that requires Vectra modules, ensure they're loaded in the correct order.
+
+3. **Disable autoloading for Vectra (last resort):**
+   ```ruby
+   # config/application.rb
+   # Add Vectra to eager load paths
+   config.eager_load_paths << Gem.find_files('vectra').first.split('/lib/').first + '/lib'
+   ```
+
+### Issue: Generator creates files but model doesn't work
+
+**Symptom:**
+```bash
+rails generate vectra:index Product embedding dimension:1536 provider:qdrant
+# Files created, but model errors
+```
+
+**Solution:**
+
+1. **Restart Rails server/console:**
+   ```bash
+   # After running generator
+   rails restart
+   ```
+
+2. **Check generated concern:**
+   ```ruby
+   # app/models/concerns/product_vector.rb
+   module ProductVector
+     extend ActiveSupport::Concern
+     
+     included do
+       include Vectra::ActiveRecord
+       has_vector :embedding, ...
+     end
+   end
+   ```
+
+3. **Check model includes concern:**
+   ```ruby
+   # app/models/product.rb
+   class Product < ApplicationRecord
+     include ProductVector  # Must be present
+   end
+   ```
+
+4. **Verify initializer:**
+   ```ruby
+   # config/initializers/vectra.rb
+   require 'vectra'  # Should be at the top
+   Vectra.configure do |config|
+     config.provider = :qdrant
+     # ...
+   end
+   ```
+
+## Debugging Tips
+
+### 1. Check what's loaded
+
+```ruby
+# In Rails console
+Vectra.constants
+# => [:Configuration, :Client, :Vector, ...]
+
+Vectra::Providers.constants
+# => Should show: [:Base, :Pinecone, :Qdrant, :Weaviate, :Pgvector, :Memory]
+
+# Check if specific provider is loaded
+defined?(Vectra::Providers::Qdrant)
+# => "constant" if loaded, nil if not
+```
+
+### 2. Force load everything
+
+```ruby
+# In Rails console or initializer
+require 'vectra'
+require 'vectra/providers/base'
+require 'vectra/providers/qdrant'
+require 'vectra/providers/pinecone'
+require 'vectra/providers/weaviate'
+require 'vectra/providers/pgvector'
+require 'vectra/providers/memory'
+```
+
+### 3. Check load order
+
+```ruby
+# In Rails console
+$LOADED_FEATURES.grep(/vectra/)
+# Shows what Vectra files are loaded and in what order
+```
+
+### 4. Test client creation
+
+```ruby
+# In Rails console
+begin
+  client = Vectra::Client.new(provider: :qdrant, host: 'http://localhost:6333')
+  puts "✅ Client created successfully"
+  puts "Provider: #{client.provider.class}"
+rescue => e
+  puts "❌ Error: #{e.class}: #{e.message}"
+  puts e.backtrace.first(5)
+end
+```
+
+## Best Practices for Rails
+
+### 1. Always require Vectra in initializer
+
+```ruby
+# config/initializers/vectra.rb
+require 'vectra'  # Always at the top
+
+Vectra.configure do |config|
+  # Configuration
+end
+```
+
+### 2. Use the generator for new models
+
+```bash
+rails generate vectra:index ModelName column_name dimension:1536 provider:qdrant
+```
+
+This ensures correct setup.
+
+### 3. Test in Rails console
+
+After setup, test in console:
+```ruby
+rails console
+
+# Test configuration
+Vectra.configuration.provider
+# => :qdrant
+
+# Test client
+client = Vectra::Client.new
+client.healthy?
+# => true
+
+# Test model (if using ActiveRecord)
+Product.vector_search([0.1, 0.2, ...], limit: 5)
+```
+
+### 4. Check logs
+
+Enable logging to see what's happening:
+```ruby
+# config/initializers/vectra.rb
+Vectra.configure do |config|
+  config.logger = Rails.logger
+  config.logger.level = :debug  # In development
+end
+```
+
+## Still Having Issues?
+
+1. **Check Vectra version:**
+   ```bash
+   bundle show vectra-client
+   ```
+
+2. **Update to latest:**
+   ```bash
+   bundle update vectra-client
+   ```
+
+3. **Check Rails version:**
+   ```bash
+   rails --version
+   ```
+
+4. **Create minimal reproduction:**
+   - New Rails app
+   - Add Vectra
+   - Reproduce issue
+   - Share steps
+
+5. **Open an issue:**
+   - [GitHub Issues](https://github.com/stokry/vectra/issues)
+   - Include Rails version, Vectra version, error message, and stack trace

data/lib/generators/vectra/templates/vectra.rb

@@ -4,6 +4,9 @@
 #
 # For more information see: https://github.com/stokry/vectra
 
+# Ensure Vectra and all Providers are loaded (important for Rails autoloading)
+require 'vectra'
+
 Vectra.configure do |config|
   # Provider configuration
   config.provider = :<%= options[:provider] %>

data/lib/vectra/active_record.rb

@@ -2,6 +2,9 @@
 
 require "active_support/concern"
 
+# Ensure Client and Providers are loaded (for Rails autoloading compatibility)
+require_relative "client" unless defined?(Vectra::Client)
+
 module Vectra
   # ActiveRecord integration for vector embeddings
   #

data/lib/vectra/client.rb

@@ -4,6 +4,14 @@
 require_relative "health_check" unless defined?(Vectra::HealthCheck)
 require_relative "configuration" unless defined?(Vectra::Configuration)
 
+# Ensure Providers are loaded before Client (for Rails autoloading compatibility)
+require_relative "providers/base" unless defined?(Vectra::Providers::Base)
+require_relative "providers/pinecone" unless defined?(Vectra::Providers::Pinecone)
+require_relative "providers/qdrant" unless defined?(Vectra::Providers::Qdrant)
+require_relative "providers/weaviate" unless defined?(Vectra::Providers::Weaviate)
+require_relative "providers/pgvector" unless defined?(Vectra::Providers::Pgvector)
+require_relative "providers/memory" unless defined?(Vectra::Providers::Memory)
+
 module Vectra
   # Unified client for vector database operations
   #
@@ -517,15 +525,15 @@ module Vectra
     def build_provider
       case config.provider
       when :pinecone
-        Providers::Pinecone.new(config)
+        Vectra::Providers::Pinecone.new(config)
       when :qdrant
-        Providers::Qdrant.new(config)
+        Vectra::Providers::Qdrant.new(config)
       when :weaviate
-        Providers::Weaviate.new(config)
+        Vectra::Providers::Weaviate.new(config)
       when :pgvector
-        Providers::Pgvector.new(config)
+        Vectra::Providers::Pgvector.new(config)
       when :memory
-        Providers::Memory.new(config)
+        Vectra::Providers::Memory.new(config)
       else
         raise UnsupportedProviderError, "Provider '#{config.provider}' is not supported"
       end

data/lib/vectra/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vectra
-  VERSION = "1.0.4"
+  VERSION = "1.0.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.6
 platform: ruby
 authors:
 - Mijo Kristo
@@ -267,6 +267,8 @@ files:
 - docs/guides/installation.md
 - docs/guides/monitoring.md
 - docs/guides/performance.md
+- docs/guides/rails-integration.md
+- docs/guides/rails-troubleshooting.md
 - docs/guides/runbooks/cache-issues.md
 - docs/guides/runbooks/high-error-rate.md
 - docs/guides/runbooks/high-latency.md