vectra-client 0.3.4 → 1.0.0

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?
@@ -299,6 +358,37 @@ module Vectra
         handle_retriable_response(e)
       end
 
+      # Extract error message from Qdrant response format
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def extract_error_message(body)
+        case body
+        when Hash
+          # Qdrant wraps errors in "status" key
+          status = body["status"] || body
+          msg = status["error"] || body["message"] || body["error_message"] || body.to_s
+
+          # Add details
+          details = status["details"] || status["error_details"]
+          if details
+            details_str = details.is_a?(Hash) ? details.to_json : details.to_s
+            msg += " (#{details_str})" unless msg.include?(details_str)
+          end
+
+          # Add field-specific errors
+          if status["errors"].is_a?(Array)
+            field_errors = status["errors"].map { |e| e.is_a?(Hash) ? e["field"] || e["message"] : e }.join(", ")
+            msg += " [Fields: #{field_errors}]" if field_errors && !msg.include?(field_errors)
+          end
+
+          msg
+        when String
+          body
+        else
+          "Unknown error"
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
       def auth_headers
         headers = {}
         headers["api-key"] = config.api_key if config.api_key && !config.api_key.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/vector.rb

@@ -106,6 +106,62 @@ module Vectra
       Math.sqrt(values.zip(other_values).sum { |a, b| (a - b)**2 })
     end
 
+    # Normalize the vector in-place (mutates the vector)
+    #
+    # @param type [Symbol] normalization type: :l2 (default) or :l1
+    # @return [Vector] self (for method chaining)
+    #
+    # @example L2 normalization (unit vector)
+    #   vector = Vectra::Vector.new(id: 'v1', values: [3.0, 4.0])
+    #   vector.normalize!
+    #   vector.values # => [0.6, 0.8] (magnitude = 1.0)
+    #
+    # @example L1 normalization (sum = 1)
+    #   vector.normalize!(type: :l1)
+    #   vector.values.sum(&:abs) # => 1.0
+    def normalize!(type: :l2)
+      case type
+      when :l2
+        magnitude = Math.sqrt(values.sum { |v| v**2 })
+        if magnitude.zero?
+          # Zero vector - cannot normalize, return as-is
+          return self
+        end
+
+        @values = values.map { |v| v / magnitude }
+      when :l1
+        sum = values.sum(&:abs)
+        if sum.zero?
+          # Zero vector - cannot normalize, return as-is
+          return self
+        end
+
+        @values = values.map { |v| v / sum }
+      else
+        raise ArgumentError, "Unknown normalization type: #{type}. Use :l2 or :l1"
+      end
+      self
+    end
+
+    # Normalize a vector array without creating a Vector object
+    #
+    # @param vector [Array<Float>] vector values to normalize
+    # @param type [Symbol] normalization type: :l2 (default) or :l1
+    # @return [Array<Float>] normalized vector values
+    #
+    # @example Normalize OpenAI embedding
+    #   embedding = openai_response['data'][0]['embedding']
+    #   normalized = Vectra::Vector.normalize(embedding)
+    #   client.upsert(vectors: [{ id: '1', values: normalized }])
+    #
+    # @example L1 normalization
+    #   normalized = Vectra::Vector.normalize([1.0, 2.0, 3.0], type: :l1)
+    def self.normalize(vector, type: :l2)
+      temp_vector = new(id: "temp", values: vector.dup)
+      temp_vector.normalize!(type: type)
+      temp_vector.values
+    end
+
     # Check equality with another vector
     #
     # @param other [Vector] the other vector

data/lib/vectra/version.rb

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

data/lib/vectra.rb

@@ -23,6 +23,7 @@ require_relative "vectra/providers/pinecone"
 require_relative "vectra/providers/qdrant"
 require_relative "vectra/providers/weaviate"
 require_relative "vectra/providers/pgvector"
+require_relative "vectra/providers/memory"
 require_relative "vectra/client"
 
 # Vectra - Unified Ruby client for vector databases
@@ -157,5 +158,24 @@ module Vectra
         **options
       )
     end
+
+    # Shortcut to create a Memory client (for testing)
+    #
+    # @param options [Hash] additional options
+    # @return [Client]
+    #
+    # @example In test environment
+    #   Vectra.configure do |config|
+    #     config.provider = :memory if Rails.env.test?
+    #   end
+    #
+    #   client = Vectra::Client.new
+    #
+    def memory(**options)
+      Client.new(
+        provider: :memory,
+        **options
+      )
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Mijo Kristo
@@ -269,6 +269,7 @@ files:
 - docs/guides/security.md
 - docs/index.md
 - docs/providers/index.md
+- docs/providers/memory.md
 - docs/providers/pgvector.md
 - docs/providers/pinecone.md
 - docs/providers/qdrant.md
@@ -303,6 +304,7 @@ files:
 - lib/vectra/logging.rb
 - lib/vectra/pool.rb
 - lib/vectra/providers/base.rb
+- lib/vectra/providers/memory.rb
 - lib/vectra/providers/pgvector.rb
 - lib/vectra/providers/pgvector/connection.rb
 - lib/vectra/providers/pgvector/index_management.rb