vectra-client 0.2.2 → 0.3.0

data/docs/examples/index.md

@@ -6,27 +6,49 @@ permalink: /examples/
 
 # Code Examples
 
-Explore practical examples to get started with Vectra:
-
-## Basic Examples
-
-- [Basic Usage]({{ site.baseurl }}/examples/basic-usage/) - Simple searches and operations
-- [Batch Operations]({{ site.baseurl }}/examples/basic-usage/#batch-operations) - Working with multiple vectors
-- [Error Handling]({{ site.baseurl }}/examples/basic-usage/#error-handling) - Proper error handling patterns
-
-## Provider-Specific Examples
-
-- [Pinecone Example]({{ site.baseurl }}/providers/pinecone/#example)
-- [Qdrant Example]({{ site.baseurl }}/providers/qdrant/#example)
-- [Weaviate Example]({{ site.baseurl }}/providers/weaviate/#example)
-- [pgvector Example]({{ site.baseurl }}/providers/pgvector/#example)
-
-## Rails Integration
-
-Check out the [pgvector guide]({{ site.baseurl }}/providers/pgvector/) for Rails ActiveRecord integration examples.
-
-## Need More Examples?
-
-- Check the [GitHub Repository](https://github.com/stokry/vectra/tree/main/examples)
-- See the [Implementation Guide](https://github.com/stokry/vectra/blob/main/IMPLEMENTATION_GUIDE.md)
-- Review [Integration Tests](https://github.com/stokry/vectra/tree/main/spec/integration)
+Practical examples to get started with Vectra.
+
+## Quick Examples
+
+<div class="tma-comparison-grid">
+  <div class="tma-comparison-card">
+    <h4>Basic Usage</h4>
+    <p>Simple searches and CRUD operations</p>
+    <a href="{{ site.baseurl }}/examples/basic-usage/">View Guide →</a>
+  </div>
+  <div class="tma-comparison-card">
+    <h4>Rails Integration</h4>
+    <p>ActiveRecord integration with has_vector</p>
+    <a href="{{ site.baseurl }}/providers/pgvector/">View Guide →</a>
+  </div>
+</div>
+
+## Provider Examples
+
+<div class="tma-comparison-grid">
+  <div class="tma-comparison-card">
+    <h4>Pinecone</h4>
+    <p>Managed cloud vector database</p>
+    <a href="{{ site.baseurl }}/providers/pinecone/">View Guide →</a>
+  </div>
+  <div class="tma-comparison-card">
+    <h4>Qdrant</h4>
+    <p>Open source, self-hosted</p>
+    <a href="{{ site.baseurl }}/providers/qdrant/">View Guide →</a>
+  </div>
+  <div class="tma-comparison-card">
+    <h4>Weaviate</h4>
+    <p>Semantic search with GraphQL</p>
+    <a href="{{ site.baseurl }}/providers/weaviate/">View Guide →</a>
+  </div>
+  <div class="tma-comparison-card">
+    <h4>pgvector</h4>
+    <p>PostgreSQL with vector support</p>
+    <a href="{{ site.baseurl }}/providers/pgvector/">View Guide →</a>
+  </div>
+</div>
+
+## More Resources
+
+- [GitHub Examples](https://github.com/stokry/vectra/tree/main/examples) - Full example files
+- [Integration Tests](https://github.com/stokry/vectra/tree/main/spec/integration) - Real-world test cases

data/docs/guides/performance.md

@@ -0,0 +1,200 @@
+---
+layout: page
+title: Performance & Optimization
+permalink: /guides/performance/
+---
+
+# Performance & Optimization
+
+Vectra provides several performance optimization features for high-throughput applications.
+
+## Async Batch Operations
+
+Process large vector sets concurrently with automatic chunking:
+
+```ruby
+require 'vectra'
+
+client = Vectra::Client.new(provider: :pinecone, api_key: ENV['PINECONE_API_KEY'])
+
+# Create a batch processor with 4 concurrent workers
+batch = Vectra::Batch.new(client, concurrency: 4)
+
+# Async upsert with automatic chunking
+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
+)
+
+puts "Upserted: #{result[:upserted_count]} vectors in #{result[:chunks]} chunks"
+puts "Errors: #{result[:errors].size}" if result[:errors].any?
+```
+
+### Batch Delete
+
+```ruby
+ids = 1000.times.map { |i| "vec_#{i}" }
+
+result = batch.delete_async(
+  index: 'my-index',
+  ids: ids,
+  chunk_size: 100
+)
+```
+
+### Batch Fetch
+
+```ruby
+ids = ['vec_1', 'vec_2', 'vec_3']
+
+vectors = batch.fetch_async(
+  index: 'my-index',
+  ids: ids,
+  chunk_size: 50
+)
+```
+
+## Streaming Results
+
+For large query result sets, use streaming to reduce memory usage:
+
+```ruby
+stream = Vectra::Streaming.new(client, page_size: 100)
+
+# Stream with a block
+stream.query_each(
+  index: 'my-index',
+  vector: query_vector,
+  total: 1000
+) do |match|
+  process_match(match)
+end
+
+# Or use lazy enumerator
+results = stream.query_stream(
+  index: 'my-index',
+  vector: query_vector,
+  total: 1000
+)
+
+# Only fetches what you need
+results.take(50).each { |m| puts m.id }
+```
+
+## Caching Layer
+
+Cache frequently queried vectors to reduce database load:
+
+```ruby
+# Create cache with 5-minute TTL
+cache = Vectra::Cache.new(ttl: 300, max_size: 1000)
+
+# Wrap client with caching
+cached_client = Vectra::CachedClient.new(client, cache: cache)
+
+# First query hits the database
+result1 = cached_client.query(index: 'idx', vector: vec, top_k: 10)
+
+# Second identical query returns cached result
+result2 = cached_client.query(index: 'idx', vector: vec, top_k: 10)
+
+# Invalidate cache when data changes
+cached_client.invalidate_index('idx')
+
+# Clear all cache
+cached_client.clear_cache
+```
+
+### Cache Statistics
+
+```ruby
+stats = cache.stats
+puts "Cache size: #{stats[:size]}/#{stats[:max_size]}"
+puts "TTL: #{stats[:ttl]} seconds"
+```
+
+## Connection Pooling (pgvector)
+
+For pgvector, use connection pooling with warmup:
+
+```ruby
+# Configure pool size
+Vectra.configure do |config|
+  config.provider = :pgvector
+  config.host = ENV['DATABASE_URL']
+  config.pool_size = 10
+  config.pool_timeout = 5
+end
+
+client = Vectra::Client.new
+
+# Warmup connections at startup
+client.provider.warmup_pool(5)
+
+# Check pool stats
+stats = client.provider.pool_stats
+puts "Available connections: #{stats[:available]}"
+puts "Checked out: #{stats[:checked_out]}"
+
+# Shutdown pool when done
+client.provider.shutdown_pool
+```
+
+## Configuration Options
+
+```ruby
+Vectra.configure do |config|
+  # Provider settings
+  config.provider = :pinecone
+  config.api_key = ENV['PINECONE_API_KEY']
+  
+  # Timeouts
+  config.timeout = 30
+  config.open_timeout = 10
+  
+  # Retry settings
+  config.max_retries = 3
+  config.retry_delay = 1
+  
+  # Batch operations
+  config.batch_size = 100
+  config.async_concurrency = 4
+  
+  # Connection pooling (pgvector)
+  config.pool_size = 10
+  config.pool_timeout = 5
+  
+  # Caching
+  config.cache_enabled = true
+  config.cache_ttl = 300
+  config.cache_max_size = 1000
+end
+```
+
+## Benchmarking
+
+Run the included benchmarks:
+
+```bash
+# Batch operations benchmark
+bundle exec ruby benchmarks/batch_operations_benchmark.rb
+
+# Connection pooling benchmark
+bundle exec ruby benchmarks/connection_pooling_benchmark.rb
+```
+
+## Best Practices
+
+1. **Batch Size**: Use batch sizes of 100-500 for optimal throughput
+2. **Concurrency**: Set concurrency to 2-4x your CPU cores
+3. **Connection Pool**: Size pool to expected concurrent requests + 20%
+4. **Cache TTL**: Set TTL based on data freshness requirements
+5. **Warmup**: Always warmup connections in production
+
+## Next Steps
+
+- [API Reference]({{ site.baseurl }}/api/overview)
+- [Provider Guides]({{ site.baseurl }}/providers)

data/docs/index.md

@@ -3,51 +3,35 @@ layout: home
 title: Vectra
 ---
 
-# Welcome to Vectra Documentation
-
-**Vectra** is a unified Ruby client for vector databases that allows you to write once and switch providers easily.
-
-## Supported Vector Databases
-
-- **Pinecone** - Managed vector database in the cloud
-- **Qdrant** - Open-source vector database
-- **Weaviate** - Open-source vector search engine
-- **PostgreSQL with pgvector** - SQL database with vector support
-
-## Quick Links
-
-- [Installation Guide]({{ site.baseurl }}/guides/installation)
-- [Getting Started]({{ site.baseurl }}/guides/getting-started)
-- [API Reference]({{ site.baseurl }}/api/overview)
-- [Examples]({{ site.baseurl }}/examples/basic-usage)
-- [Contributing]({{ site.baseurl }}/community/contributing)
-
-## Key Features
-
-- 🔄 **Provider Agnostic** - Switch between different vector database providers with minimal code changes
-- 🚀 **Easy Integration** - Works seamlessly with Rails and other Ruby frameworks
-- 📊 **Vector Operations** - Create, search, update, and delete vectors
-- 🔌 **Multiple Providers** - Support for leading vector database platforms
-- 📈 **Instrumentation** - Built-in support for Datadog and New Relic monitoring
-- 🗄️ **ActiveRecord Integration** - Native support for Rails models
-
-## Get Started
-
 ```ruby
 require 'vectra'
 
-# Initialize client
-client = Vectra::Client.new(provider: :pinecone, api_key: 'your-key')
+# Initialize any provider with the same API
+client = Vectra::Client.new(
+  provider: :pinecone,     # or :qdrant, :weaviate, :pgvector
+  api_key: ENV['API_KEY'],
+  host: 'your-host.example.com'
+)
 
-# Upsert vectors
+# Store vectors with metadata
 client.upsert(
   vectors: [
-    { id: '1', values: [0.1, 0.2, 0.3], metadata: { text: 'example' } }
+    { 
+      id: 'doc-1', 
+      values: [0.1, 0.2, 0.3, ...],  # Your embedding
+      metadata: { title: 'Getting Started with AI' }
+    }
   ]
 )
 
-# Search
-results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
-```
+# Search by similarity
+results = client.query(
+  vector: [0.1, 0.2, 0.3, ...],
+  top_k: 10,
+  filter: { category: 'tutorials' }
+)
 
-For more detailed examples, see [Basic Usage]({{ site.baseurl }}/examples/basic-usage).
+results.each do |match|
+  puts "#{match['id']}: #{match['score']}"
+end
+```

data/docs/providers/index.md

@@ -6,57 +6,76 @@ permalink: /providers/
 
 # Vector Database Providers
 
-Vectra supports multiple vector database providers. Choose the one that best fits your needs:
+Vectra supports multiple vector database providers. Choose the one that best fits your needs.
 
 ## Supported Providers
 
-| Provider | Type | Best For | Documentation |
-|----------|------|----------|---|
-| **Pinecone** | Managed Cloud | Production, Fully managed | [Guide]({{ site.baseurl }}/providers/pinecone) |
-| **Qdrant** | Open Source | Self-hosted, High performance | [Guide]({{ site.baseurl }}/providers/qdrant) |
-| **Weaviate** | Open Source | Semantic search, GraphQL | [Guide]({{ site.baseurl }}/providers/weaviate) |
-| **PostgreSQL + pgvector** | SQL Database | SQL integration, ACID | [Guide]({{ site.baseurl }}/providers/pgvector) |
+| Provider | Type | Best For |
+|----------|------|----------|
+| [**Pinecone**]({{ site.baseurl }}/providers/pinecone) | Managed Cloud | Production, Zero ops |
+| [**Qdrant**]({{ site.baseurl }}/providers/qdrant) | Open Source | Self-hosted, Performance |
+| [**Weaviate**]({{ site.baseurl }}/providers/weaviate) | Open Source | Semantic search, GraphQL |
+| [**pgvector**]({{ site.baseurl }}/providers/pgvector) | PostgreSQL | SQL integration, ACID |
 
 ## Quick Comparison
 
-### Pinecone
-- ✅ Fully managed service
-- ✅ Easy setup
-- ✅ Scalable
-- ❌ Cloud only
-- ❌ Paid service
-
-### Qdrant
-- ✅ Open source
-- ✅ Self-hosted
-- ✅ High performance
-- ✅ Multiple deployment options
-- ❌ More configuration needed
-
-### Weaviate
-- ✅ Open source
-- ✅ Semantic search
-- ✅ GraphQL API
-- ✅ Multi-model support
-- ❌ More complex
-
-### PostgreSQL + pgvector
-- ✅ SQL database
-- ✅ ACID transactions
-- ✅ Existing infrastructure
-- ✅ Affordable
-- ❌ Not specialized for vectors
+<div class="tma-comparison-grid">
+  <div class="tma-comparison-card">
+    <h4>Pinecone</h4>
+    <ul>
+      <li class="pro">Fully managed service</li>
+      <li class="pro">Easy setup</li>
+      <li class="pro">Highly scalable</li>
+      <li class="con">Cloud only</li>
+      <li class="con">Paid service</li>
+    </ul>
+  </div>
+  <div class="tma-comparison-card">
+    <h4>Qdrant</h4>
+    <ul>
+      <li class="pro">Open source</li>
+      <li class="pro">Self-hosted option</li>
+      <li class="pro">High performance</li>
+      <li class="pro">Cloud option available</li>
+      <li class="con">More configuration</li>
+    </ul>
+  </div>
+  <div class="tma-comparison-card">
+    <h4>Weaviate</h4>
+    <ul>
+      <li class="pro">Open source</li>
+      <li class="pro">Semantic search</li>
+      <li class="pro">GraphQL API</li>
+      <li class="pro">Multi-model support</li>
+      <li class="con">More complex setup</li>
+    </ul>
+  </div>
+  <div class="tma-comparison-card">
+    <h4>pgvector</h4>
+    <ul>
+      <li class="pro">SQL database</li>
+      <li class="pro">ACID transactions</li>
+      <li class="pro">Use existing Postgres</li>
+      <li class="pro">Very affordable</li>
+      <li class="con">Not vector-specialized</li>
+    </ul>
+  </div>
+</div>
 
 ## Switching Providers
 
 One of Vectra's key features is easy provider switching:
 
 ```ruby
-# All it takes is changing one line!
-client = Vectra::Client.new(provider: :qdrant)
+# Just change the provider - your code stays the same!
+client = Vectra::Client.new(provider: :qdrant, host: 'localhost:6333')
 
-# All your code remains the same
-results = client.query(vector: [0.1, 0.2, 0.3])
+# All operations work identically
+client.upsert(vectors: [...])
+results = client.query(vector: [...], top_k: 5)
 ```
 
-See the [Getting Started Guide]({{ site.baseurl }}/guides/getting-started) for more information.
+## Next Steps
+
+- [Getting Started Guide]({{ site.baseurl }}/guides/getting-started)
+- [API Reference]({{ site.baseurl }}/api/overview)

data/lib/vectra/batch.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Vectra
+  # Batch operations with concurrent processing
+  #
+  # Provides async batch upsert capabilities with configurable concurrency
+  # and automatic chunking of large vector sets.
+  #
+  # @example Async batch upsert
+  #   batch = Vectra::Batch.new(client, concurrency: 4)
+  #   result = batch.upsert_async(
+  #     index: 'my-index',
+  #     vectors: large_vector_array,
+  #     chunk_size: 100
+  #   )
+  #   puts "Upserted: #{result[:upserted_count]}"
+  #
+  class Batch
+    DEFAULT_CONCURRENCY = 4
+    DEFAULT_CHUNK_SIZE = 100
+
+    attr_reader :client, :concurrency
+
+    # Initialize a new Batch processor
+    #
+    # @param client [Client] the Vectra client
+    # @param concurrency [Integer] max concurrent requests (default: 4)
+    def initialize(client, concurrency: DEFAULT_CONCURRENCY)
+      @client = client
+      @concurrency = [concurrency, 1].max
+    end
+
+    # Perform async batch upsert with concurrent requests
+    #
+    # @param index [String] the index name
+    # @param vectors [Array<Hash>] vectors to upsert
+    # @param namespace [String, nil] optional namespace
+    # @param chunk_size [Integer] vectors per chunk (default: 100)
+    # @return [Hash] aggregated result with :upserted_count, :chunks, :errors
+    def upsert_async(index:, vectors:, namespace: nil, chunk_size: DEFAULT_CHUNK_SIZE)
+      chunks = vectors.each_slice(chunk_size).to_a
+      return { upserted_count: 0, chunks: 0, errors: [] } if chunks.empty?
+
+      results = process_chunks_concurrently(chunks) do |chunk|
+        client.upsert(index: index, vectors: chunk, namespace: namespace)
+      end
+
+      aggregate_results(results, vectors.size)
+    end
+
+    # Perform async batch delete with concurrent requests
+    #
+    # @param index [String] the index name
+    # @param ids [Array<String>] IDs to delete
+    # @param namespace [String, nil] optional namespace
+    # @param chunk_size [Integer] IDs per chunk (default: 100)
+    # @return [Hash] aggregated result
+    def delete_async(index:, ids:, namespace: nil, chunk_size: DEFAULT_CHUNK_SIZE)
+      chunks = ids.each_slice(chunk_size).to_a
+      return { deleted_count: 0, chunks: 0, errors: [] } if chunks.empty?
+
+      results = process_chunks_concurrently(chunks) do |chunk|
+        client.delete(index: index, ids: chunk, namespace: namespace)
+      end
+
+      aggregate_delete_results(results, ids.size)
+    end
+
+    # Perform async batch fetch with concurrent requests
+    #
+    # @param index [String] the index name
+    # @param ids [Array<String>] IDs to fetch
+    # @param namespace [String, nil] optional namespace
+    # @param chunk_size [Integer] IDs per chunk (default: 100)
+    # @return [Hash<String, Vector>] merged results
+    def fetch_async(index:, ids:, namespace: nil, chunk_size: DEFAULT_CHUNK_SIZE)
+      chunks = ids.each_slice(chunk_size).to_a
+      return {} if chunks.empty?
+
+      results = process_chunks_concurrently(chunks) do |chunk|
+        client.fetch(index: index, ids: chunk, namespace: namespace)
+      end
+
+      merge_fetch_results(results)
+    end
+
+    private
+
+    def process_chunks_concurrently(chunks)
+      pool = Concurrent::FixedThreadPool.new(concurrency)
+      futures = []
+
+      chunks.each_with_index do |chunk, index|
+        futures << Concurrent::Future.execute(executor: pool) do
+          { index: index, result: yield(chunk), error: nil }
+        rescue StandardError => e
+          { index: index, result: nil, error: e }
+        end
+      end
+
+      # Wait for all futures and collect results
+      results = futures.map(&:value)
+      pool.shutdown
+      pool.wait_for_termination(30)
+
+      results.sort_by { |r| r[:index] }
+    end
+
+    def aggregate_results(results, total_vectors)
+      errors = results.select { |r| r[:error] }.map { |r| r[:error] }
+      successful = results.reject { |r| r[:error] }
+      upserted = successful.sum { |r| r.dig(:result, :upserted_count) || 0 }
+
+      {
+        upserted_count: upserted,
+        total_vectors: total_vectors,
+        chunks: results.size,
+        successful_chunks: successful.size,
+        errors: errors
+      }
+    end
+
+    def aggregate_delete_results(results, total_ids)
+      errors = results.select { |r| r[:error] }.map { |r| r[:error] }
+      successful = results.reject { |r| r[:error] }
+
+      {
+        deleted_count: total_ids - (errors.size * (total_ids / results.size.to_f).ceil),
+        total_ids: total_ids,
+        chunks: results.size,
+        successful_chunks: successful.size,
+        errors: errors
+      }
+    end
+
+    def merge_fetch_results(results)
+      merged = {}
+      results.each do |r|
+        next if r[:error] || r[:result].nil?
+
+        merged.merge!(r[:result])
+      end
+      merged
+    end
+  end
+end