vectra-client 0.3.4 → 1.0.0

data/lib/vectra/client.rb

@@ -98,8 +98,26 @@ module Vectra
     #     filter: { category: 'programming' }
     #   )
     #
-    def query(index:, vector:, top_k: 10, namespace: nil, filter: nil,
+    # @example Chainable query builder
+    #   results = client.query("my-index")
+    #     .vector([0.1, 0.2, 0.3])
+    #     .top_k(10)
+    #     .filter(category: "programming")
+    #     .with_metadata
+    #     .execute
+    #
+    def query(index_arg = nil, index: nil, vector: nil, top_k: 10, namespace: nil, filter: nil,
               include_values: false, include_metadata: true)
+      # If called with a positional index string only, return a query builder:
+      #   client.query("docs").vector(vec).top_k(10).filter(...).execute
+      if index_arg && index.nil? && vector.nil? && !block_given?
+        return QueryBuilder.new(self, index_arg)
+      end
+
+      # Handle positional argument for index in non-builder case
+      index = index_arg if index_arg && index.nil?
+
+      # Backwards-compatible path: perform query immediately
       validate_index!(index)
       validate_query_vector!(vector)
 
@@ -269,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]
@@ -276,6 +359,137 @@ module Vectra
       provider.provider_name
     end
 
+    # Quick health check - tests if provider connection is healthy
+    #
+    # @param timeout [Float] timeout in seconds (default: 5)
+    # @return [Boolean] true if connection is healthy
+    #
+    # @example
+    #   if client.healthy?
+    #     client.upsert(...)
+    #   else
+    #     handle_unhealthy_connection
+    #   end
+    def healthy?
+      start = Time.now
+      provider.list_indexes
+      true
+    rescue StandardError => e
+      log_error("Health check failed", e)
+      false
+    ensure
+      duration = ((Time.now - start) * 1000).round(2) if defined?(start)
+      log_debug("Health check completed in #{duration}ms") if duration
+    end
+
+    # Ping provider and get connection health status with latency
+    #
+    # @param timeout [Float] timeout in seconds (default: 5)
+    # @return [Hash] health status with :healthy, :provider, :latency_ms
+    #
+    # @example
+    #   status = client.ping
+    #   puts "Provider: #{status[:provider]}, Healthy: #{status[:healthy]}, Latency: #{status[:latency_ms]}ms"
+    def ping
+      start = Time.now
+      healthy = true
+      error_info = nil
+
+      begin
+        provider.list_indexes
+      rescue StandardError => e
+        healthy = false
+        error_info = { error: e.class.name, error_message: e.message }
+        log_error("Health check failed", e)
+      end
+
+      duration = ((Time.now - start) * 1000).round(2)
+
+      result = {
+        healthy: healthy,
+        provider: provider_name,
+        latency_ms: duration
+      }
+
+      result.merge!(error_info) if error_info
+      result
+    end
+
+    # Chainable query builder
+    #
+    # @api public
+    # @example
+    #   results = client.query("docs")
+    #     .vector(embedding)
+    #     .top_k(20)
+    #     .namespace("prod")
+    #     .filter(category: "ruby")
+    #     .with_metadata
+    #     .execute
+    #
+    class QueryBuilder
+      def initialize(client, index)
+        @client = client
+        @index = index
+        @vector = nil
+        @top_k = 10
+        @namespace = nil
+        @filter = nil
+        @include_values = false
+        @include_metadata = true
+      end
+
+      attr_reader :index
+
+      def vector(value)
+        @vector = value
+        self
+      end
+
+      def top_k(value)
+        @top_k = value.to_i
+        self
+      end
+
+      def namespace(value)
+        @namespace = value
+        self
+      end
+
+      def filter(value = nil, **kwargs)
+        @filter = value || kwargs
+        self
+      end
+
+      def with_values
+        @include_values = true
+        self
+      end
+
+      def with_metadata
+        @include_metadata = true
+        self
+      end
+
+      def without_metadata
+        @include_metadata = false
+        self
+      end
+
+      # Execute the built query and return a QueryResult
+      def execute
+        @client.query(
+          index: @index,
+          vector: @vector,
+          top_k: @top_k,
+          namespace: @namespace,
+          filter: @filter,
+          include_values: @include_values,
+          include_metadata: @include_metadata
+        )
+      end
+    end
+
     private
 
     def build_config(provider_name, api_key, environment, host, options)
@@ -306,6 +520,8 @@ module Vectra
         Providers::Weaviate.new(config)
       when :pgvector
         Providers::Pgvector.new(config)
+      when :memory
+        Providers::Memory.new(config)
       else
         raise UnsupportedProviderError, "Provider '#{config.provider}' is not supported"
       end
@@ -317,11 +533,32 @@ module Vectra
       raise ValidationError, "Index name cannot be empty" if index.empty?
     end
 
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def validate_vectors!(vectors)
       raise ValidationError, "Vectors cannot be nil" if vectors.nil?
       raise ValidationError, "Vectors must be an array" unless vectors.is_a?(Array)
       raise ValidationError, "Vectors cannot be empty" if vectors.empty?
+
+      # Check dimension consistency
+      first_vector = vectors.first
+      first_values = first_vector.is_a?(Vector) ? first_vector.values : first_vector[:values]
+      first_dim = first_values&.size
+
+      return unless first_dim
+
+      vectors.each_with_index do |vec, index|
+        values = vec.is_a?(Vector) ? vec.values : vec[:values]
+        dim = values&.size
+
+        next unless dim && dim != first_dim
+
+        raise ValidationError,
+              "Inconsistent vector dimensions at index #{index}: " \
+              "expected #{first_dim}, got #{dim}. " \
+              "All vectors in a batch must have the same dimension."
+      end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     def validate_query_vector!(vector)
       raise ValidationError, "Query vector cannot be nil" if vector.nil?
@@ -340,5 +577,20 @@ module Vectra
       raise ValidationError, "ID must be a string" unless id.is_a?(String)
       raise ValidationError, "ID cannot be empty" if id.empty?
     end
+
+    def log_error(message, error = nil)
+      return unless config.logger
+
+      config.logger.error("[Vectra] #{message}")
+      config.logger.error("[Vectra] #{error.class}: #{error.message}") if error
+      config.logger.error("[Vectra] #{error.backtrace&.first(3)&.join("\n")}") if error&.backtrace
+    end
+
+    def log_debug(message, data = nil)
+      return unless config.logger
+
+      config.logger.debug("[Vectra] #{message}")
+      config.logger.debug("[Vectra] #{data.inspect}") if data
+    end
   end
 end

data/lib/vectra/configuration.rb

@@ -11,7 +11,7 @@ module Vectra
   #   end
   #
   class Configuration
-    SUPPORTED_PROVIDERS = %i[pinecone qdrant weaviate pgvector].freeze
+    SUPPORTED_PROVIDERS = %i[pinecone qdrant weaviate pgvector memory].freeze
 
     attr_accessor :api_key, :environment, :host, :timeout, :open_timeout,
                   :max_retries, :retry_delay, :logger, :pool_size, :pool_timeout,
@@ -117,7 +117,7 @@ module Vectra
 
     # Providers that don't require API key (local instances)
     def api_key_optional_provider?
-      %i[qdrant pgvector].include?(provider)
+      %i[qdrant pgvector memory].include?(provider)
     end
 
     def validate_provider_specific!
@@ -130,6 +130,8 @@ module Vectra
         validate_weaviate!
       when :pgvector
         validate_pgvector!
+      when :memory
+        # Memory provider has no special requirements
       end
     end
 

data/lib/vectra/credential_rotation.rb

@@ -37,13 +37,12 @@ module Vectra
 
     # Test if secondary key is valid
     #
-    # @param timeout [Float] Test timeout in seconds
     # @return [Boolean] true if secondary key works
-    def test_secondary(timeout: 5)
+    def test_secondary
       return false if secondary_key.nil? || secondary_key.empty?
 
       client = build_test_client(secondary_key)
-      client.healthy?(timeout: timeout)
+      client.healthy?
     rescue StandardError
       false
     end

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/base.rb

@@ -232,16 +232,34 @@ module Vectra
       #
       # @param body [Hash, String, nil] response body
       # @return [String]
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def extract_error_message(body)
         case body
         when Hash
-          body["message"] || body["error"] || body.to_s
+          # Primary error message
+          msg = body["message"] || body["error"] || body["error_message"] || body.to_s
+
+          # Add context from details
+          details = body["details"] || body["error_details"] || body["detail"]
+          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 available
+          if body["errors"].is_a?(Array)
+            field_errors = body["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
 
       # Log debug information
       #

data/lib/vectra/providers/memory.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Providers
+    # In-memory vector database provider for testing
+    #
+    # This provider stores all vectors in memory using Ruby hashes.
+    # Perfect for testing without external dependencies.
+    #
+    # @example Usage in tests
+    #   Vectra.configure do |config|
+    #     config.provider = :memory if Rails.env.test?
+    #   end
+    #
+    #   client = Vectra::Client.new
+    #   client.upsert(index: 'test', vectors: [...])
+    #
+    class Memory < Base
+      def initialize(config)
+        super
+        # Storage structure: @storage[index][namespace][id] = Vector
+        @storage = Hash.new { |h, k| h[k] = Hash.new { |h2, k2| h2[k2] = {} } }
+        @index_configs = {} # Store index configurations (dimension, metric)
+      end
+
+      # @see Base#provider_name
+      def provider_name
+        :memory
+      end
+
+      # @see Base#upsert
+      def upsert(index:, vectors:, namespace: nil)
+        normalized = normalize_vectors(vectors)
+        ns = namespace || ""
+
+        normalized.each do |vec|
+          # Infer dimension from first vector if not set
+          if @index_configs[index].nil?
+            @index_configs[index] = {
+              dimension: vec[:values].length,
+              metric: "cosine"
+            }
+          end
+
+          # Store vector
+          vector_obj = Vector.new(
+            id: vec[:id],
+            values: vec[:values],
+            metadata: vec[:metadata] || {}
+          )
+          @storage[index][ns][vec[:id]] = vector_obj
+        end
+
+        log_debug("Upserted #{normalized.size} vectors to #{index}")
+        { upserted_count: normalized.size }
+      end
+
+      # @see Base#query
+      def query(index:, vector:, top_k: 10, namespace: nil, filter: nil,
+                include_values: false, include_metadata: true)
+        ns = namespace || ""
+        candidates = @storage[index][ns].values
+
+        # Apply metadata filter
+        if filter
+          candidates = candidates.select { |v| matches_filter?(v, filter) }
+        end
+
+        # Calculate similarity scores
+        matches = candidates.map do |vec|
+          score = calculate_similarity(vector, vec.values, index)
+          build_match(vec, score, include_values, include_metadata)
+        end
+
+        # Sort by score (descending) and take top_k
+        matches.sort_by! { |m| -m[:score] }
+        matches = matches.first(top_k)
+
+        log_debug("Query returned #{matches.size} results")
+        QueryResult.from_response(matches: matches, namespace: namespace)
+      end
+
+      # @see Base#fetch
+      def fetch(index:, ids:, namespace: nil)
+        ns = namespace || ""
+        vectors = {}
+
+        ids.each do |id|
+          vec = @storage[index][ns][id]
+          vectors[id] = vec if vec
+        end
+
+        vectors
+      end
+
+      # @see Base#update
+      def update(index:, id:, metadata:, namespace: nil)
+        ns = namespace || ""
+        vec = @storage[index][ns][id]
+
+        raise NotFoundError, "Vector '#{id}' not found in index '#{index}'" unless vec
+
+        # Merge metadata
+        new_metadata = (vec.metadata || {}).merge(metadata.transform_keys(&:to_s))
+        updated_vec = Vector.new(
+          id: vec.id,
+          values: vec.values,
+          metadata: new_metadata,
+          sparse_values: vec.sparse_values
+        )
+        @storage[index][ns][id] = updated_vec
+
+        log_debug("Updated vector #{id}")
+        { updated: true }
+      end
+
+      # @see Base#delete
+      def delete(index:, ids: nil, namespace: nil, filter: nil, delete_all: false)
+        ns = namespace || ""
+
+        if delete_all
+          @storage[index].clear
+        elsif ids
+          ids.each { |id| @storage[index][ns].delete(id) }
+        elsif namespace && !filter
+          @storage[index].delete(ns)
+        elsif filter
+          # Delete vectors matching filter
+          @storage[index][ns].delete_if { |_id, vec| matches_filter?(vec, filter) }
+        else
+          raise ValidationError, "Must specify ids, filter, namespace, or delete_all"
+        end
+
+        log_debug("Deleted vectors from #{index}")
+        { deleted: true }
+      end
+
+      # @see Base#list_indexes
+      def list_indexes
+        @index_configs.keys.map { |name| describe_index(index: name) }
+      end
+
+      # @see Base#describe_index
+      def describe_index(index:)
+        config = @index_configs[index]
+        raise NotFoundError, "Index '#{index}' not found" unless config
+
+        {
+          name: index,
+          dimension: config[:dimension],
+          metric: config[:metric],
+          status: "ready"
+        }
+      end
+
+      # @see Base#stats
+      def stats(index:, namespace: nil)
+        config = @index_configs[index]
+        raise NotFoundError, "Index '#{index}' not found" unless config
+
+        if namespace
+          ns = namespace
+          count = @storage[index][ns].size
+          namespaces = { ns => { vector_count: count } }
+        else
+          # Count all namespaces
+          namespaces = {}
+          @storage[index].each do |ns, vectors|
+            namespaces[ns] = { vector_count: vectors.size }
+          end
+          count = @storage[index].values.sum(&:size)
+        end
+
+        {
+          total_vector_count: count,
+          dimension: config[:dimension],
+          namespaces: namespaces
+        }
+      end
+
+      # Clear all stored data (useful for tests)
+      #
+      # @return [void]
+      def clear!
+        @storage.clear
+        @index_configs.clear
+      end
+
+      private
+
+      # Calculate similarity score based on index metric
+      def calculate_similarity(query_vector, candidate_vector, index)
+        config = @index_configs[index] || { metric: "cosine" }
+        metric = config[:metric] || "cosine"
+
+        case metric.to_s.downcase
+        when "euclidean", "l2"
+          # Convert distance to similarity (1 / (1 + distance))
+          distance = euclidean_distance(query_vector, candidate_vector)
+          1.0 / (1.0 + distance)
+        when "dot_product", "inner_product", "dot"
+          dot_product(query_vector, candidate_vector)
+        else # cosine (default)
+          cosine_similarity(query_vector, candidate_vector)
+        end
+      end
+
+      # Calculate cosine similarity
+      def cosine_similarity(vec_a, vec_b)
+        raise ArgumentError, "Vectors must have same dimension" if vec_a.length != vec_b.length
+
+        dot = vec_a.zip(vec_b).sum { |a, b| a * b }
+        mag_a = Math.sqrt(vec_a.sum { |v| v**2 })
+        mag_b = Math.sqrt(vec_b.sum { |v| v**2 })
+
+        return 0.0 if mag_a.zero? || mag_b.zero?
+
+        dot / (mag_a * mag_b)
+      end
+
+      # Calculate Euclidean distance
+      def euclidean_distance(vec_a, vec_b)
+        raise ArgumentError, "Vectors must have same dimension" if vec_a.length != vec_b.length
+
+        Math.sqrt(vec_a.zip(vec_b).sum { |a, b| (a - b)**2 })
+      end
+
+      # Calculate dot product
+      def dot_product(vec_a, vec_b)
+        raise ArgumentError, "Vectors must have same dimension" if vec_a.length != vec_b.length
+
+        vec_a.zip(vec_b).sum { |a, b| a * b }
+      end
+
+      # Check if vector matches filter
+      def matches_filter?(vector, filter)
+        filter.all? do |key, value|
+          vec_value = vector.metadata[key.to_s]
+          matches_filter_value?(vec_value, value)
+        end
+      end
+
+      # Check if a value matches filter criteria
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def matches_filter_value?(actual, expected)
+        case expected
+        when Hash
+          # Support operators like { "$gt" => 5, "$lt" => 10 }
+          expected.all? do |op, val|
+            case op.to_s
+            when "$eq"
+              actual == val
+            when "$ne"
+              actual != val
+            when "$gt"
+              actual.is_a?(Numeric) && val.is_a?(Numeric) && actual > val
+            when "$gte"
+              actual.is_a?(Numeric) && val.is_a?(Numeric) && actual >= val
+            when "$lt"
+              actual.is_a?(Numeric) && val.is_a?(Numeric) && actual < val
+            when "$lte"
+              actual.is_a?(Numeric) && val.is_a?(Numeric) && actual <= val
+            when "$in"
+              val.is_a?(Array) && val.include?(actual)
+            else
+              actual == expected
+            end
+          end
+        when Array
+          expected.include?(actual)
+        else
+          actual == expected
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # Build match hash from vector
+      def build_match(vector, score, include_values, include_metadata)
+        match = {
+          id: vector.id,
+          score: score
+        }
+        match[:values] = vector.values if include_values
+        match[:metadata] = vector.metadata if include_metadata
+        match[:sparse_values] = vector.sparse_values if vector.sparse?
+        match
+      end
+
+      # Override validate_config! - Memory provider doesn't need host or API key
+      # rubocop:disable Naming/PredicateMethod
+      def validate_config!
+        # Memory provider has no special requirements
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+    end
+  end
+end