vectra-client 1.0.8 → 1.1.1

data/lib/vectra/middleware/logging.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Logging middleware for tracking operations
+    #
+    # Logs before and after each operation, including timing information.
+    #
+    # @example With default logger
+    #   Vectra::Client.use Vectra::Middleware::Logging
+    #
+    # @example With custom logger
+    #   logger = Logger.new($stdout)
+    #   Vectra::Client.use Vectra::Middleware::Logging, logger: logger
+    #
+    # @example Per-client logging
+    #   client = Vectra::Client.new(
+    #     provider: :qdrant,
+    #     middleware: [Vectra::Middleware::Logging]
+    #   )
+    #
+    class Logging < Base
+      def initialize(logger: nil)
+        super()
+        @logger = logger || Vectra.configuration.logger
+      end
+
+      def before(request)
+        return unless @logger
+
+        @start_time = Time.now
+        @logger.info(
+          "[Vectra] #{request.operation.upcase} " \
+          "index=#{request.index} " \
+          "namespace=#{request.namespace || 'default'}"
+        )
+      end
+
+      def after(request, response)
+        return unless @logger
+        return unless @start_time
+
+        duration_ms = ((Time.now - @start_time) * 1000).round(2)
+        response.metadata[:duration_ms] = duration_ms
+
+        if response.success?
+          @logger.info("[Vectra] ✅ #{request.operation} completed in #{duration_ms}ms")
+        else
+          @logger.error("[Vectra] ❌ #{request.operation} failed: #{response.error.message}")
+        end
+      end
+
+      def on_error(request, error)
+        return unless @logger
+
+        @logger.error(
+          "[Vectra] 💥 #{request.operation} exception: #{error.class} - #{error.message}"
+        )
+      end
+    end
+  end
+end

data/lib/vectra/middleware/pii_redaction.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # PII Redaction middleware for protecting sensitive data
+    #
+    # Automatically redacts Personally Identifiable Information (PII) from
+    # metadata before upserting to vector databases.
+    #
+    # @example With default patterns (email, phone, SSN)
+    #   Vectra::Client.use Vectra::Middleware::PIIRedaction
+    #
+    # @example With custom patterns
+    #   custom_patterns = {
+    #     credit_card: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/,
+    #     api_key: /sk-[a-zA-Z0-9]{32}/
+    #   }
+    #   Vectra::Client.use Vectra::Middleware::PIIRedaction, patterns: custom_patterns
+    #
+    class PIIRedaction < Base
+      # Default PII patterns
+      DEFAULT_PATTERNS = {
+        email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/,
+        phone: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/,
+        ssn: /\b\d{3}-\d{2}-\d{4}\b/,
+        credit_card: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/
+      }.freeze
+
+      def initialize(patterns: DEFAULT_PATTERNS)
+        super()
+        @patterns = patterns
+      end
+
+      def before(request)
+        return unless request.operation == :upsert
+        return unless request.params[:vectors]
+
+        # Redact PII from metadata in all vectors
+        request.params[:vectors].each do |vector|
+          next unless vector[:metadata]
+
+          vector[:metadata] = redact_metadata(vector[:metadata])
+        end
+      end
+
+      private
+
+      # Redact PII from metadata hash
+      #
+      # @param metadata [Hash] Metadata to redact
+      # @return [Hash] Redacted metadata
+      def redact_metadata(metadata)
+        metadata.transform_values do |value|
+          next value unless value.is_a?(String)
+
+          redacted = value.dup
+          @patterns.each do |type, pattern|
+            redacted.gsub!(pattern, "[REDACTED_#{type.upcase}]")
+          end
+          redacted
+        end
+      end
+    end
+  end
+end

data/lib/vectra/middleware/request.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Request object passed through middleware chain
+    #
+    # @example Basic usage
+    #   request = Request.new(
+    #     operation: :upsert,
+    #     index: 'products',
+    #     namespace: 'prod',
+    #     vectors: [{ id: 'doc-1', values: [0.1, 0.2, 0.3] }]
+    #   )
+    #
+    #   request.operation # => :upsert
+    #   request.index     # => 'products'
+    #   request.namespace # => 'prod'
+    #   request.metadata[:custom_key] = 'custom_value'
+    #
+    class Request
+      attr_accessor :operation, :index, :namespace, :params, :metadata
+
+      # @param operation [Symbol] The operation type (:upsert, :query, :delete, etc.)
+      # @param params [Hash] All parameters for the operation
+      def initialize(operation:, **params)
+        @operation = operation
+        @index = params[:index]
+        @namespace = params[:namespace]
+        @params = params
+        @metadata = {}
+      end
+
+      # Convert request back to hash for provider call
+      #
+      # @return [Hash] Parameters hash
+      def to_h
+        params
+      end
+
+      # Get the provider from params
+      #
+      # @return [Symbol, nil] Provider name
+      def provider
+        params[:provider]
+      end
+
+      # Check if this is a write operation
+      #
+      # @return [Boolean]
+      def write_operation?
+        [:upsert, :delete, :update, :create_index, :delete_index].include?(operation)
+      end
+
+      # Check if this is a read operation
+      #
+      # @return [Boolean]
+      def read_operation?
+        [:query, :text_search, :hybrid_search, :fetch, :list_indexes, :describe_index, :stats].include?(operation)
+      end
+    end
+  end
+end

data/lib/vectra/middleware/response.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Response object returned through middleware chain
+    #
+    # @example Success response
+    #   response = Response.new(result: { success: true })
+    #   response.success? # => true
+    #   response.result   # => { success: true }
+    #
+    # @example Error response
+    #   response = Response.new(error: StandardError.new('Failed'))
+    #   response.failure? # => true
+    #   response.error    # => #<StandardError: Failed>
+    #
+    # @example With metadata
+    #   response = Response.new(result: [])
+    #   response.metadata[:duration_ms] = 45
+    #   response.metadata[:cache_hit] = true
+    #
+    class Response
+      attr_accessor :result, :error, :metadata
+
+      # @param result [Object] The successful result
+      # @param error [Exception, nil] The error if failed
+      def initialize(result: nil, error: nil)
+        @result = result
+        @error = error
+        @metadata = {}
+      end
+
+      # Check if the response was successful
+      #
+      # @return [Boolean] true if no error
+      def success?
+        error.nil?
+      end
+
+      # Check if the response failed
+      #
+      # @return [Boolean] true if error present
+      def failure?
+        !success?
+      end
+
+      # Raise error if present
+      #
+      # @raise [Exception] The stored error
+      # @return [void]
+      def raise_if_error!
+        raise error if error
+      end
+
+      # Get the result or raise error
+      #
+      # @return [Object] The result
+      # @raise [Exception] If error present
+      def value!
+        raise_if_error!
+        result
+      end
+    end
+  end
+end

data/lib/vectra/middleware/retry.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Retry middleware for handling transient failures
+    #
+    # Automatically retries failed requests with configurable backoff strategy.
+    #
+    # @example With default settings (3 attempts, exponential backoff)
+    #   Vectra::Client.use Vectra::Middleware::Retry
+    #
+    # @example With custom settings
+    #   Vectra::Client.use Vectra::Middleware::Retry, max_attempts: 5, backoff: :linear
+    #
+    # @example Per-client retry
+    #   client = Vectra::Client.new(
+    #     provider: :pinecone,
+    #     middleware: [[Vectra::Middleware::Retry, { max_attempts: 3 }]]
+    #   )
+    #
+    class Retry < Base
+      # @param max_attempts [Integer] Maximum number of attempts (default: 3)
+      # @param backoff [Symbol, Numeric] Backoff strategy (:exponential, :linear) or fixed delay
+      def initialize(max_attempts: 3, backoff: :exponential)
+        super()
+        @max_attempts = max_attempts
+        @backoff = backoff
+      end
+
+      def call(request, app)
+        attempt = 0
+        last_error = nil
+
+        loop do
+          attempt += 1
+
+          begin
+            response = app.call(request)
+
+            # If successful, return immediately
+            if response.success?
+              response.metadata[:retry_count] = attempt - 1
+              return response
+            end
+
+            # If error is retryable and we haven't exceeded max attempts, retry
+            if response.error && retryable?(response.error) && attempt < @max_attempts
+              sleep(backoff_delay(attempt))
+              next
+            end
+
+            # Error is not retryable or max attempts reached, return response
+            response.metadata[:retry_count] = attempt - 1
+            return response
+          rescue StandardError => e
+            last_error = e
+
+            # If error is retryable and we haven't exceeded max attempts, retry
+            if retryable?(e) && attempt < @max_attempts
+              sleep(backoff_delay(attempt))
+              next
+            end
+
+            # Error is not retryable or max attempts reached, raise
+            raise
+          end
+        end
+      end
+
+      private
+
+      # Check if error is retryable
+      #
+      # @param error [Exception] The error to check
+      # @return [Boolean] true if error is retryable
+      def retryable?(error)
+        error.is_a?(Vectra::RateLimitError) ||
+          error.is_a?(Vectra::ConnectionError) ||
+          error.is_a?(Vectra::TimeoutError) ||
+          error.is_a?(Vectra::ServerError)
+      end
+
+      # Calculate backoff delay
+      #
+      # @param attempt [Integer] Current attempt number
+      # @return [Float] Delay in seconds
+      def backoff_delay(attempt)
+        case @backoff
+        when :exponential
+          # 0.2s, 0.4s, 0.8s, 1.6s, ...
+          (2**(attempt - 1)) * 0.2
+        when :linear
+          # 0.5s, 1.0s, 1.5s, 2.0s, ...
+          attempt * 0.5
+        when Numeric
+          @backoff
+        else
+          1.0
+        end
+      end
+    end
+  end
+end

data/lib/vectra/middleware/stack.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Middleware stack executor
+    #
+    # Builds and executes a chain of middleware around provider calls.
+    # Similar to Rack middleware, each middleware wraps the next one
+    # in the chain until reaching the actual provider.
+    #
+    # @example Basic usage
+    #   provider = Vectra::Providers::Memory.new
+    #   middlewares = [LoggingMiddleware.new, RetryMiddleware.new]
+    #   stack = Stack.new(provider, middlewares)
+    #
+    #   result = stack.call(:upsert, index: 'test', vectors: [...])
+    #
+    class Stack
+      # @param provider [Vectra::Providers::Base] The actual provider
+      # @param middlewares [Array<Base>] Array of middleware instances
+      def initialize(provider, middlewares = [])
+        @provider = provider
+        @middlewares = middlewares
+      end
+
+      # Execute the middleware stack for an operation
+      #
+      # @param operation [Symbol] The operation to perform (:upsert, :query, etc.)
+      # @param params [Hash] The operation parameters
+      # @return [Object] The result from the provider
+      # @raise [Exception] Any error from middleware or provider
+      def call(operation, **params)
+        request = Request.new(operation: operation, **params)
+
+        # Build middleware chain
+        app = build_chain(request)
+
+        # Execute chain
+        response = app.call(request)
+
+        # Raise if error occurred
+        raise response.error if response.error
+
+        response.result
+      end
+
+      private
+
+      # Build the middleware chain
+      #
+      # @param request [Request] The request object (unused here, but available)
+      # @return [Proc] The complete middleware chain
+      def build_chain(_request)
+        # Final app: actual provider call
+        final_app = lambda do |req|
+          # Remove middleware-specific params before calling provider
+          provider_params = req.to_h.except(:provider)
+          result = @provider.public_send(req.operation, **provider_params)
+          Response.new(result: result)
+        rescue StandardError => e
+          Response.new(error: e)
+        end
+
+        # Wrap with middlewares in reverse order
+        # (last middleware in array is first to execute)
+        @middlewares.reverse.inject(final_app) do |next_app, middleware|
+          lambda do |req|
+            middleware.call(req, next_app)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vectra/providers/memory.rb

@@ -80,6 +80,32 @@ module Vectra
         QueryResult.from_response(matches: matches, namespace: namespace)
       end
 
+      # Text-only search using simple keyword matching in metadata
+      #
+      # For testing purposes only. Performs case-insensitive keyword matching
+      # in metadata values. Not a real BM25/full-text search implementation.
+      #
+      # @param index [String] index name
+      # @param text [String] text query for keyword search
+      # @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 text_search(index:, text:, top_k:, namespace: nil, filter: nil,
+                      include_values: false, include_metadata: true)
+        ns = namespace || ""
+        candidates = filter_candidates(@storage[index][ns].values, filter)
+        text_lower = text.to_s.downcase
+
+        matches = find_text_matches(candidates, text_lower, include_values, include_metadata)
+        matches = matches.sort_by { |m| -m[:score] }.first(top_k)
+
+        log_debug("Text search returned #{matches.size} results")
+        QueryResult.from_response(matches: matches, namespace: namespace)
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil)
         ns = namespace || ""
@@ -293,6 +319,36 @@ module Vectra
         true
       end
       # rubocop:enable Naming/PredicateMethod
+
+      # Filter candidates by metadata filter
+      def filter_candidates(candidates, filter)
+        return candidates unless filter
+
+        candidates.select { |v| matches_filter?(v, filter) }
+      end
+
+      # Find text matches in candidates
+      def find_text_matches(candidates, text_lower, include_values, include_metadata)
+        candidates.map do |vec|
+          metadata_text = build_metadata_text(vec)
+          next unless metadata_text.include?(text_lower)
+
+          score = calculate_text_score(text_lower, metadata_text)
+          build_match(vec, score, include_values, include_metadata)
+        end.compact
+      end
+
+      # Build metadata text string for searching
+      def build_metadata_text(vector)
+        (vector.metadata || {}).values.map(&:to_s).join(" ").downcase
+      end
+
+      # Calculate text match score based on word matches
+      def calculate_text_score(query_text, metadata_text)
+        query_words = query_text.split(/\s+/)
+        matched_words = query_words.count { |word| metadata_text.include?(word) }
+        matched_words.to_f / query_words.size
+      end
     end
   end
 end

data/lib/vectra/providers/pgvector.rb

@@ -28,6 +28,7 @@ module Vectra
     #   )
     #   client.upsert(index: 'documents', vectors: [...])
     #
+    # rubocop:disable Metrics/ClassLength
     class Pgvector < Base
       include Connection
       include SqlHelpers
@@ -162,6 +163,54 @@ module Vectra
         )
       end
 
+      # Text-only search using PostgreSQL full-text search
+      #
+      # @param index [String] table name
+      # @param text [String] text query for full-text search
+      # @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 text_search(index:, text:, top_k:, namespace: nil, filter: nil,
+                      include_values: false, include_metadata: true,
+                      text_column: "content")
+        ensure_table_exists!(index)
+
+        select_cols = ["id"]
+        select_cols << "embedding" if include_values
+        select_cols << "metadata" if include_metadata
+
+        # Use ts_rank for scoring
+        text_score = "ts_rank(to_tsvector('english', COALESCE(#{quote_ident(text_column)}, '')), " \
+                     "plainto_tsquery('english', #{escape_literal(text)}))"
+        select_cols << "#{text_score} AS 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("Text search returned #{matches.size} results")
+
+        QueryResult.from_response(
+          matches: matches,
+          namespace: namespace
+        )
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil)
         ensure_table_exists!(index)
@@ -361,5 +410,6 @@ module Vectra
         raise ConfigurationError, "Host (connection URL or hostname) must be configured for pgvector"
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/vectra/providers/qdrant.rb

@@ -110,6 +110,45 @@ module Vectra
         handle_hybrid_search_response(response, alpha, namespace)
       end
 
+      # Text-only search using Qdrant's BM25 text search
+      #
+      # @param index [String] collection name
+      # @param text [String] text query for keyword search
+      # @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 text_search(index:, text:, top_k:, namespace: nil, filter: nil,
+                      include_values: false, include_metadata: true)
+        qdrant_filter = build_filter(filter, namespace)
+        body = {
+          query: { text: text },
+          limit: top_k,
+          with_vector: include_values,
+          with_payload: include_metadata
+        }
+
+        body[:filter] = qdrant_filter if qdrant_filter
+
+        response = with_error_handling do
+          connection.post("/collections/#{index}/points/query", body)
+        end
+
+        if response.success?
+          matches = transform_search_results(response.body["result"] || [])
+          log_debug("Text search returned #{matches.size} results")
+
+          QueryResult.from_response(
+            matches: matches,
+            namespace: namespace
+          )
+        else
+          handle_error(response)
+        end
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil) # rubocop:disable Lint/UnusedMethodArgument
         point_ids = ids.map { |id| generate_point_id(id) }