vectra-client 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcc42d23052b076d9efcb085b9490b3d21b0e1b101a8edb3d9fca500d72ac2cd
-  data.tar.gz: 5abe33ef210d55e3cda6ffa8f80ca1ecadcea8632c46eb9ce78c824f35684c68
+  metadata.gz: b0d48b8a6205df9a0d6545e3772e26da09f826f03d56751a6fa997e1a73d89f1
+  data.tar.gz: 25dc65ad327e03e7912a0b938739b6acf1d6708efd8fa41773d9bbae1053e3dc
 SHA512:
-  metadata.gz: 40aaec0556a2de07028db2e75ad2ebf463f51728336fc508676a567837a45d1be00174ed679601a1aa5f976a05605c10c86817dd99616bc38b63350fa1ed9e63
-  data.tar.gz: 1a3bfad7f776a429be42f591af896c3c9e9ba55a45eb58dffda8b9fa50190d5248552bfab87038ab53e04183d2cbe5fcade506bf0cc99580b1435c50a30b64b9
+  metadata.gz: 68fc7d7a2c941733bb8f42007dffa52989daedeb362da62c094d05dec7d02f8ca6d7ca8763194e9b51b4ecfe3f7a6e8db4418c7589caab31943f055f75f4c48a
+  data.tar.gz: f40ab28eb011943d4961e22c5d31b5a816a81cea1a2bf6afa238004adaa1cdd8558f10b0ee8d56376d6fc737788b16fc1acb7088778d8461ecb3a8db2ff85580

data/CHANGELOG.md

@@ -1,12 +1,25 @@
 # Changelog
 
-## [v0.3.4](https://github.com/stokry/vectra/tree/v0.3.4) (2026-01-12)
+## [v0.4.0](https://github.com/stokry/vectra/tree/v0.4.0) (2026-01-12)
 
-[Full Changelog](https://github.com/stokry/vectra/compare/v0.3.3...v0.3.4)
+### Added
+- Memory provider for in-memory vector storage
+- QueryBuilder for chainable query API
+- Batch operations with concurrent processing
+- Vector normalization methods (L2, L1)
+- Enhanced error message extraction
 
 ### Fixed
-- Fixed Weaviate provider DELETE request WebMock stub to include query parameters
-- Fixed RuboCop offenses: empty string interpolation, redundant else, ambiguous block associations, and style issues
+- Weaviate DELETE request query parameters
+- Qdrant error message extraction from nested status
+- Client ping error info capture
+- Credential rotation timeout parameter handling
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.3.4...v0.4.0)
+
+## [v0.3.4](https://github.com/stokry/vectra/tree/v0.3.4) (2026-01-12)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.3.3...v0.3.4)
 
 ## [v0.3.3](https://github.com/stokry/vectra/tree/v0.3.3) (2026-01-09)
 

data/README.md

@@ -17,6 +17,7 @@
 | **Qdrant** | Open Source | ✅ Supported |
 | **Weaviate** | Open Source | ✅ Supported |
 | **pgvector** | PostgreSQL | ✅ Supported |
+| **Memory** | In-Memory | ✅ Testing only |
 
 ## Installation
 
@@ -48,12 +49,38 @@ client.upsert(
   ]
 )
 
-# Search
+# Search (classic API)
 results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
 results.each { |match| puts "#{match.id}: #{match.score}" }
 
+# Search (chainable Query Builder)
+results = client
+  .query('docs')
+  .vector([0.1, 0.2, 0.3])
+  .top_k(5)
+  .with_metadata
+  .execute
+
+results.each do |match|
+  puts "#{match.id}: #{match.score}"
+end
+
+# Normalize embeddings (for better cosine similarity)
+embedding = openai_response['data'][0]['embedding']
+normalized = Vectra::Vector.normalize(embedding)
+client.upsert(vectors: [{ id: 'doc-1', values: normalized }])
+
 # Delete
 client.delete(ids: ['doc-1', 'doc-2'])
+
+# Health check
+if client.healthy?
+  puts "Connection is healthy"
+end
+
+# Ping with latency
+status = client.ping
+puts "Provider: #{status[:provider]}, Latency: #{status[:latency_ms]}ms"
 ```
 
 ## Provider Examples
@@ -69,10 +96,16 @@ client = Vectra.qdrant(host: 'http://localhost:6333')
 client = Vectra.qdrant(host: 'https://your-cluster.qdrant.io', api_key: ENV['QDRANT_API_KEY'])
 
 # Weaviate
-client = Vectra.weaviate(host: 'http://localhost:8080', api_key: ENV['WEAVIATE_API_KEY'])
+client = Vectra.weaviate(
+  api_key: ENV['WEAVIATE_API_KEY'],
+  host: 'https://your-weaviate-instance'
+)
 
 # pgvector (PostgreSQL)
 client = Vectra.pgvector(connection_url: 'postgres://user:pass@localhost/mydb')
+
+# Memory (in-memory, testing only)
+client = Vectra.memory
 ```
 
 ## Features

data/docs/examples/real-world.md

@@ -37,6 +37,8 @@ class ProductSearchService
 
   def search(query:, category: nil, price_range: nil, limit: 20)
     query_embedding = generate_embedding(query)
+    # Normalize for better cosine similarity
+    query_embedding = Vectra::Vector.normalize(query_embedding)
     
     filter = {}
     filter[:category] = category if category
@@ -68,9 +70,12 @@ class ProductSearchService
 
   def generate_embedding(text)
     # Use your embedding model (OpenAI, sentence-transformers, etc.)
-    OpenAI::Client.new.embeddings(
+    embedding = OpenAI::Client.new.embeddings(
       parameters: { model: "text-embedding-ada-002", input: text }
     )["data"][0]["embedding"]
+    
+    # Normalize embeddings before storing
+    Vectra::Vector.normalize(embedding)
   end
 
   def fallback_search(query, category)
@@ -257,14 +262,14 @@ class TenantDocumentService
     query_embedding = generate_embedding(query)
     
     # Ensure tenant isolation via namespace
-    results = @client.query(
-      index: "documents",
-      vector: query_embedding,
-      top_k: limit,
-      namespace: "tenant-#{@tenant_id}",
-      filter: { tenant_id: @tenant_id }, # Double protection
-      include_metadata: true
-    )
+    results = @client
+      .query("documents")
+      .vector(query_embedding)
+      .top_k(limit)
+      .namespace("tenant-#{@tenant_id}")
+      .filter(tenant_id: @tenant_id) # Double protection
+      .with_metadata
+      .execute
     
     # Audit log
     @audit.log_access(
@@ -325,9 +330,11 @@ class DocumentIndexer
 
   def index_large_dataset(documents, concurrency: 4)
     total = documents.size
-    processed = 0
     errors = []
     
+    # Create batch client with specified concurrency
+    batch_client = Vectra::Batch.new(@client, concurrency: concurrency)
+    
     # Convert to vectors
     vectors = documents.map do |doc|
       {
@@ -337,25 +344,27 @@ class DocumentIndexer
       }
     end
     
-    # Process in async batches
-    result = @batch_client.upsert_async(
+    # Process in async batches with progress tracking
+    result = batch_client.upsert_async(
       index: "documents",
       vectors: vectors,
-      concurrency: concurrency,
-      on_progress: proc { |success, failed, total|
-        processed = success + failed
-        progress = (processed.to_f / total * 100).round(1)
+      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})"
-      },
-      on_error: proc { |error, vector|
-        errors << { id: vector[:id], error: error.message }
+        puts "  Chunk #{chunk}/#{total_chunks} | Success: #{stats[:success_count]}, Failed: #{stats[:failed_count]}"
       }
     )
     
     {
-      success: result[:success],
-      failed: result[:failed],
-      errors: errors,
+      success: result[:upserted_count],
+      failed: result[:errors].size,
+      errors: result[:errors],
       total: total
     }
   end
@@ -475,6 +484,37 @@ module VectraHelper
 end
 ```
 
+## Testing with the Memory Provider
+
+For fast, deterministic tests you can run Vectra entirely in memory without any external services:
+
+```ruby
+# config/initializers/vectra.rb (test environment)
+Vectra.configure do |config|
+  config.provider = :memory if Rails.env.test?
+end
+
+RSpec.describe ProductSearchService do
+  let(:client) { Vectra::Client.new } # uses memory provider in test
+
+  before do
+    client.provider.clear! if client.provider.respond_to?(:clear!)
+
+    client.upsert(
+      index: "products",
+      vectors: [
+        { id: "p1", values: [0.1, 0.2], metadata: { name: "Test Product" } }
+      ]
+    )
+  end
+
+  it "returns relevant products" do
+    results = client.query(index: "products", vector: [0.1, 0.2], top_k: 5)
+    expect(results.ids).to include("p1")
+  end
+end
+```
+
 ## Best Practices
 
 ### 1. Always Use Caching for Frequent Queries

data/docs/guides/getting-started.md

@@ -43,17 +43,49 @@ client.upsert(
 ### Query (Search)
 
 ```ruby
+# Classic API
 results = client.query(
   vector: [0.1, 0.2, 0.3],
   top_k: 5,
   include_metadata: true
 )
 
-results.matches.each do |match|
-  puts "ID: #{match['id']}, Score: #{match['score']}"
+results.each do |match|
+  puts "ID: #{match.id}, Score: #{match.score}"
+end
+
+# Chainable Query Builder
+results = client
+  .query("my-index")
+  .vector([0.1, 0.2, 0.3])
+  .top_k(5)
+  .with_metadata
+  .execute
+
+results.each do |match|
+  puts "ID: #{match.id}, Score: #{match.score}"
 end
 ```
 
+### Normalize Embeddings
+
+For better cosine similarity results, normalize your embeddings before upserting:
+
+```ruby
+# Normalize OpenAI embeddings (recommended)
+embedding = openai_response['data'][0]['embedding']
+normalized = Vectra::Vector.normalize(embedding)
+client.upsert(vectors: [{ id: 'doc-1', values: normalized }])
+
+# Or normalize in-place
+vector = Vectra::Vector.new(id: 'doc-1', values: embedding)
+vector.normalize!  # L2 normalization (default, unit vector)
+client.upsert(vectors: [vector])
+
+# L1 normalization (sum of absolute values = 1)
+vector.normalize!(type: :l1)
+```
+
 ### Delete Vectors
 
 ```ruby
@@ -68,6 +100,42 @@ puts "Index dimension: #{stats['dimension']}"
 puts "Vector count: #{stats['vector_count']}"
 ```
 
+### Health Check & Ping
+
+```ruby
+# Quick health check
+if client.healthy?
+  client.upsert(...)
+else
+  handle_unhealthy_connection
+end
+
+# Ping with latency measurement
+status = client.ping
+puts "Provider: #{status[:provider]}"
+puts "Healthy: #{status[:healthy]}"
+puts "Latency: #{status[:latency_ms]}ms"
+
+if status[:error]
+  puts "Error: #{status[:error_message]}"
+end
+```
+
+### Dimension Validation
+
+Vectra automatically validates that all vectors in a batch have the same dimension:
+
+```ruby
+# This will raise ValidationError
+vectors = [
+  { id: "vec1", values: [0.1, 0.2, 0.3] }, # 3 dimensions
+  { id: "vec2", values: [0.4, 0.5] }        # 2 dimensions - ERROR!
+]
+
+client.upsert(vectors: vectors)
+# => ValidationError: Inconsistent vector dimensions at index 1: expected 3, got 2
+```
+
 ## Configuration
 
 Create a configuration file (Rails: `config/initializers/vectra.rb`):

data/docs/providers/index.md

@@ -16,6 +16,7 @@ Vectra supports multiple vector database providers. Choose the one that best fit
 | [**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 |
+| [**Memory**]({{ site.baseurl }}/providers/memory) | In-Memory | Testing, CI, local dev |
 
 ## Quick Comparison
 
@@ -75,6 +76,17 @@ client.upsert(vectors: [...])
 results = client.query(vector: [...], top_k: 5)
 ```
 
+For **tests and CI** you can use the in-memory provider:
+
+```ruby
+# config/initializers/vectra.rb (test environment)
+Vectra.configure do |config|
+  config.provider = :memory if Rails.env.test?
+end
+
+client = Vectra::Client.new
+```
+
 ## Next Steps
 
 - [Getting Started Guide]({{ site.baseurl }}/guides/getting-started)

data/docs/providers/memory.md

@@ -0,0 +1,145 @@
+---
+layout: page
+title: Memory Provider
+permalink: /providers/memory/
+---
+
+# Memory Provider
+
+The **Memory provider** is an in-memory vector store built into Vectra.
+It is designed **exclusively for testing, local development, and CI** – no external database required.
+
+> Not for production use. All data lives in process memory and is lost when the process exits.
+
+## When to Use
+
+- ✅ RSpec / Minitest suites (fast, isolated tests)
+- ✅ Local development without provisioning Pinecone/Qdrant/Weaviate/pgvector
+- ✅ CI pipelines where external services are not available
+- ❌ Not suitable for production workloads
+
+## Setup
+
+### Global Configuration (Rails Example)
+
+```ruby
+# config/initializers/vectra.rb
+Vectra.configure do |config|
+  config.provider = :memory if Rails.env.test?
+end
+```
+
+Then in your application code:
+
+```ruby
+client = Vectra::Client.new
+```
+
+### Direct Construction
+
+```ruby
+require "vectra"
+
+client = Vectra.memory
+```
+
+No `host`, `api_key`, or environment configuration is required.
+
+## Features
+
+- ✅ `upsert` – store vectors in memory
+- ✅ `query` – cosine similarity search (with optional metadata filtering)
+- ✅ `fetch` – retrieve vectors by ID
+- ✅ `update` – merge metadata for existing vectors
+- ✅ `delete` – delete by IDs, namespace, filter, or `delete_all`
+- ✅ `list_indexes` / `describe_index` – basic index metadata (dimension, metric)
+- ✅ `stats` – vector counts per namespace
+- ✅ `clear!` – wipe all data between tests
+
+## Basic Usage
+
+```ruby
+client = Vectra.memory
+
+# Upsert
+client.upsert(
+  index: "documents",
+  vectors: [
+    {
+      id: "doc-1",
+      values: [0.1, 0.2, 0.3],
+      metadata: { title: "Hello", category: "docs" }
+    }
+  ],
+  namespace: "test-suite"
+)
+
+# Query
+results = client.query(
+  index: "documents",
+  vector: [0.1, 0.2, 0.3],
+  top_k: 5,
+  namespace: "test-suite",
+  filter: { category: "docs" },
+  include_metadata: true
+)
+
+results.each do |match|
+  puts "#{match.id}: #{match.metadata["title"]} (score=#{match.score.round(3)})"
+end
+```
+
+## Metadata Filtering
+
+The Memory provider supports a subset of the same filter operators as other providers:
+
+```ruby
+results = client.query(
+  index: "products",
+  vector: query_embedding,
+  top_k: 10,
+  filter: {
+    status: ["active", "preview"],         # IN
+    price: { "$gte" => 10, "$lte" => 100 },# range
+    brand: { "$ne" => "Acme" }             # not equal
+  },
+  include_metadata: true
+)
+```
+
+Supported operators:
+
+- Equality: `{ field: "value" }` or `{ field: { "$eq" => "value" } }`
+- Inequality: `{ field: { "$ne" => "value" } }`
+- Ranges: `{ field: { "$gt" => 10 } }`, `{ "$gte" => 10 }`, `{ "$lt" => 20 }`, `{ "$lte" => 20 }`
+- Arrays / IN: `{ field: ["a", "b"] }` or `{ field: { "$in" => ["a", "b"] } }`
+
+## Resetting State Between Tests
+
+The Memory provider exposes a `clear!` method to reset all in-memory state:
+
+```ruby
+RSpec.describe "MyService" do
+  let(:client) { Vectra.memory }
+
+  before do
+    client.provider.clear! if client.provider.respond_to?(:clear!)
+  end
+
+  # your tests...
+end
+```
+
+You can also call `clear!` on the provider obtained from a regular `Vectra::Client`:
+
+```ruby
+client = Vectra::Client.new(provider: :memory)
+client.provider.clear!
+```
+
+## Limitations
+
+- Not distributed – data lives only in the current Ruby process.
+- No persistence – all vectors are lost when the process exits or `clear!` is called.
+- Intended for **testing and development only**, not for production traffic.
+

data/docs/providers/weaviate.md

@@ -18,53 +18,112 @@ docker run -p 8080:8080 semitechnologies/weaviate:latest
 
 ### Connect with Vectra
 
+You can either use the convenience constructor:
+
+```ruby
+client = Vectra.weaviate(
+  api_key: ENV["WEAVIATE_API_KEY"], # optional for local / required for cloud
+  host: "http://localhost:8080"     # or your cloud endpoint
+)
+```
+
+or configure via `Vectra::Client`:
+
 ```ruby
 client = Vectra::Client.new(
   provider: :weaviate,
-  host: 'localhost',
-  port: 8080,
-  class_name: 'Document'
+  api_key: ENV["WEAVIATE_API_KEY"],
+  host: "https://your-weaviate-instance"
 )
 ```
 
 ## Features
 
-- ✅ Upsert vectors
-- ✅ Query/search
-- ✅ Delete vectors
-- ✅ Class management
-- ✅ Metadata filtering
-- ✅ Semantic search
+- ✅ Upsert vectors into Weaviate classes (per-index `class`)
+- ✅ Vector similarity search via GraphQL `nearVector`
+- ✅ Fetch by IDs
+- ✅ Metadata filtering (exact match, ranges, arrays)
+- ✅ Namespace support via `_namespace` property
+- ✅ Delete by IDs or filter
+- ✅ List and describe classes
+- ✅ Basic stats via GraphQL `Aggregate`
 
-## Example
+## Basic Example
 
 ```ruby
-# Initialize client
-client = Vectra::Client.new(
-  provider: :weaviate,
-  host: 'localhost',
-  port: 8080
+require "vectra"
+
+client = Vectra.weaviate(
+  api_key: ENV["WEAVIATE_API_KEY"],
+  host: "https://your-weaviate-instance"
 )
 
+index = "Document" # Weaviate class name
+
 # Upsert vectors
 client.upsert(
+  index: index,
   vectors: [
-    { id: 'doc-1', values: [0.1, 0.2, 0.3], metadata: { category: 'news' } }
-  ]
+    {
+      id: "doc-1",
+      values: [0.1, 0.2, 0.3],
+      metadata: {
+        title: "Getting started with Vectra",
+        category: "docs"
+      }
+    }
+  ],
+  namespace: "prod" # stored as _namespace property
 )
 
-# Search
-results = client.query(vector: [0.1, 0.2, 0.3], top_k: 5)
+# Query with metadata filter
+results = client.query(
+  index: index,
+  vector: [0.1, 0.2, 0.3],
+  top_k: 5,
+  namespace: "prod",
+  filter: { category: "docs" },
+  include_metadata: true
+)
+
+results.each do |match|
+  puts "#{match.id} (score=#{match.score.round(3)}): #{match.metadata["title"]}"
+end
+```
+
+## Advanced Filtering
+
+Vectra maps simple Ruby hashes to Weaviate `where` filters:
+
+```ruby
+results = client.query(
+  index: "Document",
+  vector: query_embedding,
+  top_k: 10,
+  filter: {
+    category: "blog",
+    views: { "$gt" => 1000 },
+    tags: ["ruby", "vectra"] # ContainsAny
+  },
+  include_metadata: true
+)
 ```
 
+Supported operators:
+
+- Equality: `{ field: "value" }` or `{ field: { "$eq" => "value" } }`
+- Inequality: `{ field: { "$ne" => "value" } }`
+- Ranges: `{ field: { "$gt" => 10 } }`, `{ "$gte" => 10 }`, `{ "$lt" => 20 }`, `{ "$lte" => 20 }`
+- Arrays: `{ field: ["a", "b"] }` (contains any), `{ field: { "$in" => ["a", "b"] } }`
+
 ## Configuration Options
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `host` | String | Yes | Weaviate host address |
-| `port` | Integer | Yes | Weaviate port (default: 8080) |
-| `class_name` | String | No | Class name for vectors |
-| `api_key` | String | No | API key if auth is enabled |
+| Option   | Type   | Required | Description                                   |
+|----------|--------|----------|-----------------------------------------------|
+| `host`   | String | Yes      | Weaviate base URL (`http://` or `https://`)  |
+| `api_key`| String | No*      | API key if auth is enabled / cloud instances |
+
+> `api_key` is optional for local, unsecured Weaviate; required for managed/cloud deployments.
 
 ## Documentation
 

data/examples/README.md

@@ -261,6 +261,18 @@ The comprehensive demo now includes **4 additional sections** demonstrating prod
 - **Error Tracking**: Sentry and Honeybadger integration
 - Production monitoring setup
 
+In addition to the classic API, the demo now also showcases the **chainable Query Builder** style:
+
+```ruby
+results = client
+  .query("documents")
+  .vector(embedding)
+  .top_k(10)
+  .filter(category: "ruby")
+  .with_metadata
+  .execute
+```
+
 ## Tips for Production
 
 ### Performance