vectra-client 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0d48b8a6205df9a0d6545e3772e26da09f826f03d56751a6fa997e1a73d89f1
-  data.tar.gz: 25dc65ad327e03e7912a0b938739b6acf1d6708efd8fa41773d9bbae1053e3dc
+  metadata.gz: f9965925f32b1b497e306ba25776f06edaba86b3c8abf8b750c8a449fe68ba5a
+  data.tar.gz: 1622d500398e1fb95b146d2792c0f29abdde93888e7b74af8fd1dc674c9bee58
 SHA512:
-  metadata.gz: 68fc7d7a2c941733bb8f42007dffa52989daedeb362da62c094d05dec7d02f8ca6d7ca8763194e9b51b4ecfe3f7a6e8db4418c7589caab31943f055f75f4c48a
-  data.tar.gz: f40ab28eb011943d4961e22c5d31b5a816a81cea1a2bf6afa238004adaa1cdd8558f10b0ee8d56376d6fc737788b16fc1acb7088778d8461ecb3a8db2ff85580
+  metadata.gz: 1911cce768648f9c48e9c94e13a7d0c51f39e81eb381a0defcbc581eb27b4cfacb56d41e1cfb776f6a2ef4522e344c32d842a550c79d5a7584bb1a84a637e605
+  data.tar.gz: bfb7cc7174a739591a8061436f47963dab2c33809db3437558f5addf9cf4dff2b15b93bc72934f1dd04821f2f93884b07f0c9f5886b4d618d9e3eff15ce907a6

data/CHANGELOG.md

@@ -1,22 +1,59 @@
 # Changelog
 
-## [v0.4.0](https://github.com/stokry/vectra/tree/v0.4.0) (2026-01-12)
+## [v1.0.0](https://github.com/stokry/vectra/tree/v1.0.0) (2026-01-12)
 
 ### 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
-- Weaviate DELETE request query parameters
-- Qdrant error message extraction from nested status
-- Client ping error info capture
-- Credential rotation timeout parameter handling
+- Hybrid search functionality for Qdrant and Weaviate providers
+- Enhanced provider capabilities and error handling
+- Support for advanced filtering and namespace operations
+- Improved vector search performance
+
+### Changed
+- Major API refinements and provider implementations
+- Enhanced test coverage and documentation
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.4.0...v1.0.0)
+
+## [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.4...v0.4.0)
 
+### Added
+- **Hybrid Search** - Combine semantic (vector) and keyword (text) search across all providers
+  - Full support for Qdrant (prefetch + rescore API)
+  - Full support for Weaviate (hybrid GraphQL with BM25)
+  - Full support for pgvector (vector similarity + PostgreSQL full-text search)
+  - Partial support for Pinecone (requires sparse vectors for true hybrid search)
+  - Alpha parameter (0.0 = pure keyword, 1.0 = pure semantic) for fine-tuning balance
+- **Batch Progress Callbacks** - Real-time visibility into batch operations
+  - `on_progress` callback with detailed statistics (processed, total, percentage, chunk info)
+  - Thread-safe progress tracking with `Concurrent::AtomicFixnum`
+  - Support for `upsert_async`, `delete_async`, and `fetch_async` methods
+- **Vector Normalization Helper** - Improve cosine similarity results
+  - `Vector.normalize!` instance method (L2 and L1 normalization)
+  - `Vector.normalize` class method for non-mutating normalization
+  - Automatic handling of zero vectors
+- **Dimension Validation** - Automatic validation of vector dimension consistency
+  - Validates all vectors in a batch have the same dimension
+  - Detailed error messages with index and expected/actual dimensions
+  - Works with both Vector objects and hash vectors
+- **Better Error Messages** - Enhanced error context and debugging
+  - Includes error details, field-specific errors, and context
+  - Improved error message format: "Main message (details) [Fields: field1, field2]"
+- **Connection Health Check** - Simple health monitoring methods
+  - `healthy?` method for quick boolean health check
+  - `ping` method with latency measurement and detailed status
+  - Automatic error logging when logger is configured
+
+### Changed
+- Improved error handling with more context in error messages
+- Enhanced batch operations with progress tracking capabilities
+
+### Documentation
+- Added comprehensive hybrid search examples and provider support matrix
+- Updated getting started guide with normalization, health checks, and dimension validation
+- Added real-world examples demonstrating new features
+
 ## [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)

data/README.md

@@ -81,6 +81,15 @@ end
 # Ping with latency
 status = client.ping
 puts "Provider: #{status[:provider]}, Latency: #{status[:latency_ms]}ms"
+
+# Hybrid search (semantic + keyword)
+# Supported by: Qdrant, Weaviate, Pinecone, pgvector
+results = client.hybrid_search(
+  index: 'docs',
+  vector: embedding,
+  text: 'ruby programming',
+  alpha: 0.7  # 70% semantic, 30% keyword
+)
 ```
 
 ## Provider Examples

data/docs/api/overview.md

@@ -111,6 +111,98 @@ Get index statistics.
 }
 ```
 
+### `hybrid_search(index:, vector:, text:, alpha:, top_k:)`
+
+Combine semantic (vector) and keyword (text) search.
+
+**Parameters:**
+- `index` (String) - Index/collection name
+- `vector` (Array) - Query vector for semantic search
+- `text` (String) - Text query for keyword search
+- `alpha` (Float) - Balance between semantic and keyword (0.0 = pure keyword, 1.0 = pure semantic)
+- `top_k` (Integer) - Number of results (default: 10)
+- `namespace` (String, optional) - Namespace
+- `filter` (Hash, optional) - Metadata filter
+- `include_values` (Boolean) - Include vector values (default: false)
+- `include_metadata` (Boolean) - Include metadata (default: true)
+
+**Example:**
+```ruby
+results = client.hybrid_search(
+  index: 'docs',
+  vector: embedding,
+  text: 'ruby programming',
+  alpha: 0.7  # 70% semantic, 30% keyword
+)
+```
+
+**Provider Support:** Qdrant ✅, Weaviate ✅, pgvector ✅, Pinecone ⚠️
+
+### `healthy?`
+
+Quick health check - returns true if provider connection is healthy.
+
+**Returns:** Boolean
+
+**Example:**
+```ruby
+if client.healthy?
+  client.upsert(...)
+end
+```
+
+### `ping`
+
+Ping provider and get connection health status with latency.
+
+**Returns:**
+```ruby
+{
+  healthy: true,
+  provider: :pinecone,
+  latency_ms: 45.23
+}
+```
+
+**Example:**
+```ruby
+status = client.ping
+puts "Latency: #{status[:latency_ms]}ms"
+```
+
+### `Vector.normalize(vector, type: :l2)`
+
+Normalize a vector array (non-mutating).
+
+**Parameters:**
+- `vector` (Array) - Vector values to normalize
+- `type` (Symbol) - Normalization type: `:l2` (default) or `:l1`
+
+**Returns:** Array of normalized values
+
+**Example:**
+```ruby
+embedding = openai_response['data'][0]['embedding']
+normalized = Vectra::Vector.normalize(embedding)
+client.upsert(vectors: [{ id: 'doc-1', values: normalized }])
+```
+
+### `vector.normalize!(type: :l2)`
+
+Normalize vector in-place (mutates the vector).
+
+**Parameters:**
+- `type` (Symbol) - Normalization type: `:l2` (default) or `:l1`
+
+**Returns:** Self (for method chaining)
+
+**Example:**
+```ruby
+vector = Vectra::Vector.new(id: 'doc-1', values: embedding)
+vector.normalize!  # L2 normalization
+client.upsert(vectors: [vector])
+```
+
 ## Error Handling
 
 ```ruby

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:

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/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/lib/vectra/client.rb

@@ -287,6 +287,71 @@ module Vectra
       provider.stats(index: index, namespace: namespace)
     end
 
+    # Hybrid search combining semantic (vector) and keyword (text) search
+    #
+    # Combines the best of both worlds: semantic understanding from vectors
+    # and exact keyword matching from text search.
+    #
+    # @param index [String] the index/collection name
+    # @param vector [Array<Float>] query vector for semantic search
+    # @param text [String] text query for keyword search
+    # @param alpha [Float] balance between semantic and keyword (0.0 = pure keyword, 1.0 = pure semantic)
+    # @param top_k [Integer] number of results to return
+    # @param namespace [String, nil] optional namespace
+    # @param filter [Hash, nil] metadata filter
+    # @param include_values [Boolean] include vector values in results
+    # @param include_metadata [Boolean] include metadata in results
+    # @return [QueryResult] search results
+    #
+    # @example Basic hybrid search
+    #   results = client.hybrid_search(
+    #     index: 'docs',
+    #     vector: embedding,
+    #     text: 'ruby programming',
+    #     alpha: 0.7  # 70% semantic, 30% keyword
+    #   )
+    #
+    # @example Pure semantic (alpha = 1.0)
+    #   results = client.hybrid_search(
+    #     index: 'docs',
+    #     vector: embedding,
+    #     text: 'ruby',
+    #     alpha: 1.0
+    #   )
+    #
+    # @example Pure keyword (alpha = 0.0)
+    #   results = client.hybrid_search(
+    #     index: 'docs',
+    #     vector: embedding,
+    #     text: 'ruby programming',
+    #     alpha: 0.0
+    #   )
+    #
+    def hybrid_search(index:, vector:, text:, alpha: 0.5, top_k: 10, namespace: nil,
+                      filter: nil, include_values: false, include_metadata: true)
+      validate_index!(index)
+      validate_query_vector!(vector)
+      raise ValidationError, "Text query cannot be nil or empty" if text.nil? || text.empty?
+      raise ValidationError, "Alpha must be between 0.0 and 1.0" unless (0.0..1.0).include?(alpha)
+
+      unless provider.respond_to?(:hybrid_search)
+        raise UnsupportedFeatureError,
+              "Hybrid search is not supported by #{provider_name} provider"
+      end
+
+      provider.hybrid_search(
+        index: index,
+        vector: vector,
+        text: text,
+        alpha: alpha,
+        top_k: top_k,
+        namespace: namespace,
+        filter: filter,
+        include_values: include_values,
+        include_metadata: include_metadata
+      )
+    end
+
     # Get the provider name
     #
     # @return [Symbol]

data/lib/vectra/errors.rb

@@ -57,6 +57,9 @@ module Vectra
   # Raised when the provider is not supported
   class UnsupportedProviderError < Error; end
 
+  # Raised when a feature is not supported by the provider
+  class UnsupportedFeatureError < Error; end
+
   # Raised when an operation times out
   class TimeoutError < Error; end
 

data/lib/vectra/providers/pgvector.rb

@@ -94,6 +94,74 @@ module Vectra
         QueryResult.from_response(matches: matches, namespace: namespace)
       end
 
+      # Hybrid search combining vector similarity and PostgreSQL full-text search
+      #
+      # Combines pgvector similarity search with PostgreSQL's native full-text search.
+      # Requires a text search column (tsvector) in your table.
+      #
+      # @param index [String] table name
+      # @param vector [Array<Float>] query vector
+      # @param text [String] text query for full-text search
+      # @param alpha [Float] balance (0.0 = full-text, 1.0 = vector)
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @param text_column [String] column name for full-text search (default: 'content')
+      # @return [QueryResult] search results
+      #
+      # @note Your table should have a text column with a tsvector index:
+      #   CREATE INDEX idx_content_fts ON my_index USING gin(to_tsvector('english', content));
+      def hybrid_search(index:, vector:, text:, alpha:, top_k:, namespace: nil,
+                        filter: nil, include_values: false, include_metadata: true,
+                        text_column: "content")
+        ensure_table_exists!(index)
+
+        vector_literal = format_vector(vector)
+        distance_op = DISTANCE_FUNCTIONS[table_metric(index)]
+
+        # Build hybrid score: alpha * vector_similarity + (1-alpha) * text_rank
+        # Vector similarity: 1 - (distance / max_distance)
+        # Text rank: ts_rank from full-text search
+        select_cols = ["id"]
+        select_cols << "embedding" if include_values
+        select_cols << "metadata" if include_metadata
+
+        # Calculate hybrid score
+        # For vector: use cosine distance (1 - distance gives similarity)
+        # For text: use ts_rank
+        vector_score = "1.0 - (embedding #{distance_op} '#{vector_literal}'::vector)"
+        text_score = "ts_rank(to_tsvector('english', COALESCE(#{quote_ident(text_column)}, '')), " \
+                     "plainto_tsquery('english', #{escape_literal(text)}))"
+
+        # Normalize scores to 0-1 range and combine with alpha
+        hybrid_score = "(#{alpha} * #{vector_score} + (1.0 - #{alpha}) * #{text_score})"
+
+        select_cols << "#{hybrid_score} AS score"
+        select_cols << "#{vector_score} AS vector_score"
+        select_cols << "#{text_score} AS text_score"
+
+        where_clauses = build_where_clauses(namespace, filter)
+        where_clauses << "to_tsvector('english', COALESCE(#{quote_ident(text_column)}, '')) @@ " \
+                         "plainto_tsquery('english', #{escape_literal(text)})"
+
+        sql = "SELECT #{select_cols.join(', ')} FROM #{quote_ident(index)}"
+        sql += " WHERE #{where_clauses.join(' AND ')}" if where_clauses.any?
+        sql += " ORDER BY score DESC"
+        sql += " LIMIT #{top_k.to_i}"
+
+        result = execute(sql)
+        matches = result.map { |row| build_match_from_row(row, include_values, include_metadata) }
+
+        log_debug("Hybrid search returned #{matches.size} results (alpha: #{alpha})")
+
+        QueryResult.from_response(
+          matches: matches,
+          namespace: namespace
+        )
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil)
         ensure_table_exists!(index)

data/lib/vectra/providers/pinecone.rb

@@ -67,6 +67,63 @@ module Vectra
         end
       end
 
+      # Hybrid search combining dense (vector) and sparse (keyword) search
+      #
+      # Pinecone supports hybrid search using sparse-dense vectors.
+      # For text-based keyword search, you need to provide sparse vectors.
+      #
+      # @param index [String] index name
+      # @param vector [Array<Float>] dense query vector
+      # @param text [String] text query (converted to sparse vector)
+      # @param alpha [Float] balance (0.0 = sparse, 1.0 = dense)
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @return [QueryResult] search results
+      #
+      # @note For proper hybrid search, you should generate sparse vectors
+      #   from text using a tokenizer (e.g., BM25). This method accepts text
+      #   but requires sparse vector generation externally.
+      def hybrid_search(index:, vector:, alpha:, top_k:, namespace: nil,
+                        filter: nil, include_values: false, include_metadata: true, text: nil)
+        # Pinecone hybrid search requires sparse vectors
+        # For now, we'll use dense vector only and log a warning
+        # In production, users should generate sparse vectors from text
+        if text
+          log_debug("Pinecone hybrid search: text parameter ignored. " \
+                    "For true hybrid search, provide sparse vectors via sparse_values parameter.")
+        end
+
+        # Use dense vector search with alpha weighting
+        # Note: Pinecone's actual hybrid search requires sparse vectors
+        # This is a simplified implementation
+        body = {
+          vector: vector.map(&:to_f),
+          topK: top_k,
+          includeValues: include_values,
+          includeMetadata: include_metadata
+        }
+        body[:namespace] = namespace if namespace
+        body[:filter] = transform_filter(filter) if filter
+
+        # Alpha is used conceptually here - Pinecone's actual hybrid search
+        # requires sparse vectors in the query
+        response = data_connection(index).post("/query", body)
+
+        if response.success?
+          log_debug("Hybrid search returned #{response.body['matches']&.size || 0} results (alpha: #{alpha})")
+          QueryResult.from_response(
+            matches: transform_matches(response.body["matches"] || []),
+            namespace: response.body["namespace"],
+            usage: response.body["usage"]
+          )
+        else
+          handle_error(response)
+        end
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil)
         params = { ids: ids }

data/lib/vectra/providers/qdrant.rb

@@ -83,6 +83,33 @@ module Vectra
         end
       end
 
+      # Hybrid search combining vector and text search
+      #
+      # Uses Qdrant's prefetch + rescore API for efficient hybrid search
+      #
+      # @param index [String] collection name
+      # @param vector [Array<Float>] query vector
+      # @param text [String] text query for keyword search
+      # @param alpha [Float] balance (0.0 = keyword, 1.0 = vector)
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @return [QueryResult] search results
+      def hybrid_search(index:, vector:, text:, alpha:, top_k:, namespace: nil,
+                        filter: nil, include_values: false, include_metadata: true)
+        qdrant_filter = build_filter(filter, namespace)
+        body = build_hybrid_search_body(vector, text, alpha, top_k, qdrant_filter,
+                                        include_values, include_metadata)
+
+        response = with_error_handling do
+          connection.post("/collections/#{index}/points/query", body)
+        end
+
+        handle_hybrid_search_response(response, alpha, namespace)
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil) # rubocop:disable Lint/UnusedMethodArgument
         point_ids = ids.map { |id| generate_point_id(id) }
@@ -280,6 +307,38 @@ module Vectra
 
       private
 
+      def build_hybrid_search_body(vector, text, alpha, top_k, filter, include_values, include_metadata)
+        body = {
+          prefetch: {
+            query: { text: text },
+            limit: top_k * 2
+          },
+          query: { vector: vector.map(&:to_f) },
+          limit: top_k,
+          params: { alpha: alpha },
+          with_vector: include_values,
+          with_payload: include_metadata
+        }
+
+        body[:prefetch][:filter] = filter if filter
+        body[:query][:filter] = filter if filter
+        body
+      end
+
+      def handle_hybrid_search_response(response, alpha, namespace)
+        if response.success?
+          matches = transform_search_results(response.body["result"] || [])
+          log_debug("Hybrid search returned #{matches.size} results (alpha: #{alpha})")
+
+          QueryResult.from_response(
+            matches: matches,
+            namespace: namespace
+          )
+        else
+          handle_error(response)
+        end
+      end
+
       def validate_config!
         super
         raise ConfigurationError, "Host must be configured for Qdrant" if config.host.nil? || config.host.empty?

data/lib/vectra/providers/weaviate.rb

@@ -102,6 +102,43 @@ module Vectra
         end
       end
 
+      # Hybrid search combining vector and BM25 text search
+      #
+      # Uses Weaviate's hybrid search API with alpha parameter
+      #
+      # @param index [String] class name
+      # @param vector [Array<Float>] query vector
+      # @param text [String] text query for BM25 search
+      # @param alpha [Float] balance (0.0 = BM25, 1.0 = vector)
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace (not used in Weaviate)
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @return [QueryResult] search results
+      def hybrid_search(index:, vector:, text:, alpha:, top_k:, namespace: nil,
+                        filter: nil, include_values: false, include_metadata: true)
+        where_filter = build_where(filter, namespace)
+        graphql = build_hybrid_search_graphql(
+          index: index,
+          vector: vector,
+          text: text,
+          alpha: alpha,
+          top_k: top_k,
+          where_filter: where_filter,
+          include_values: include_values,
+          include_metadata: include_metadata
+        )
+        body = { "query" => graphql }
+
+        response = with_error_handling do
+          connection.post("#{API_BASE_PATH}/graphql", body)
+        end
+
+        handle_hybrid_search_response(response, index, alpha, namespace,
+                                      include_values, include_metadata)
+      end
+
       # rubocop:disable Metrics/PerceivedComplexity
       def fetch(index:, ids:, namespace: nil)
         body = {
@@ -294,6 +331,54 @@ module Vectra
 
       private
 
+      def build_hybrid_search_graphql(index:, vector:, text:, alpha:, top_k:,
+                                      where_filter:, include_values:, include_metadata:)
+        selection_block = build_selection_fields(include_values, include_metadata).join(" ")
+        build_graphql_query(index, top_k, text, alpha, vector, where_filter, selection_block)
+      end
+
+      def build_graphql_query(index, top_k, text, alpha, vector, where_filter, selection_block)
+        <<~GRAPHQL
+          {
+            Get {
+              #{index}(
+                limit: #{top_k}
+                hybrid: {
+                  query: "#{text.gsub('"', '\\"')}"
+                  alpha: #{alpha}
+                }
+                nearVector: { vector: [#{vector.map { |v| format('%.10f', v.to_f) }.join(', ')}] }
+                #{"where: #{JSON.generate(where_filter)}" if where_filter}
+              ) {
+                #{selection_block}
+              }
+            }
+          }
+        GRAPHQL
+      end
+
+      def build_selection_fields(include_values, include_metadata)
+        fields = ["_additional { id distance }"]
+        fields << "vector" if include_values
+        fields << "metadata" if include_metadata
+        fields
+      end
+
+      def handle_hybrid_search_response(response, index, alpha, namespace,
+                                        include_values, include_metadata)
+        if response.success?
+          matches = extract_query_matches(response.body, index, include_values, include_metadata)
+          log_debug("Hybrid search returned #{matches.size} results (alpha: #{alpha})")
+
+          QueryResult.from_response(
+            matches: matches,
+            namespace: namespace
+          )
+        else
+          handle_error(response)
+        end
+      end
+
       def validate_config!
         super
         raise ConfigurationError, "Host must be configured for Weaviate" if config.host.nil? || config.host.empty?

data/lib/vectra/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Mijo Kristo