vectra-client 1.0.7 → 1.1.0

data/lib/vectra/middleware/cost_tracker.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Cost tracking middleware for monitoring API usage costs
+    #
+    # Tracks estimated costs per operation based on provider pricing.
+    # Costs are stored in response metadata and can be aggregated.
+    #
+    # @example With default pricing
+    #   Vectra::Client.use Vectra::Middleware::CostTracker
+    #
+    # @example With custom pricing
+    #   custom_pricing = {
+    #     pinecone: { read: 0.0001, write: 0.0002 },
+    #     qdrant: { read: 0.00005, write: 0.0001 }
+    #   }
+    #   Vectra::Client.use Vectra::Middleware::CostTracker, pricing: custom_pricing
+    #
+    # @example With cost callback
+    #   Vectra::Client.use Vectra::Middleware::CostTracker, on_cost: ->(event) {
+    #     puts "Cost: $#{event[:cost_usd]} for #{event[:operation]}"
+    #   }
+    #
+    class CostTracker < Base
+      # Default pricing per operation (in USD)
+      # These are estimated values - check provider pricing for actual costs
+      DEFAULT_PRICING = {
+        pinecone: { read: 0.0001, write: 0.0002 },
+        qdrant: { read: 0.00005, write: 0.0001 },
+        weaviate: { read: 0.00008, write: 0.00015 },
+        pgvector: { read: 0.0, write: 0.0 }, # Self-hosted, no API costs
+        memory: { read: 0.0, write: 0.0 }    # In-memory, no costs
+      }.freeze
+
+      # @param pricing [Hash] Custom pricing structure
+      # @param on_cost [Proc] Callback to invoke with cost events
+      def initialize(pricing: DEFAULT_PRICING, on_cost: nil)
+        super()
+        @pricing = pricing
+        @on_cost = on_cost
+      end
+
+      def after(request, response)
+        return unless response.success?
+
+        provider = request.provider || :unknown
+        operation_type = write_operation?(request.operation) ? :write : :read
+
+        cost = calculate_cost(provider, operation_type, request)
+        response.metadata[:cost_usd] = cost
+
+        # Invoke callback if provided
+        return unless @on_cost
+
+        @on_cost.call(
+          operation: request.operation,
+          provider: provider,
+          index: request.index,
+          cost_usd: cost,
+          timestamp: Time.now
+        )
+      end
+
+      private
+
+      # Check if operation is a write operation
+      #
+      # @param operation [Symbol] The operation type
+      # @return [Boolean] true if write operation
+      def write_operation?(operation)
+        [:upsert, :delete, :update, :create_index, :delete_index].include?(operation)
+      end
+
+      # Calculate cost for operation
+      #
+      # @param provider [Symbol] Provider name
+      # @param operation_type [Symbol] :read or :write
+      # @param request [Request] The request object
+      # @return [Float] Cost in USD
+      def calculate_cost(provider, operation_type, request)
+        rate = @pricing.dig(provider, operation_type) || 0.0
+        multiplier = operation_multiplier(request)
+        rate * multiplier
+      end
+
+      # Calculate multiplier for operation based on batch size
+      #
+      # @param request [Request] The request object
+      # @return [Integer, Float] Multiplier for the base rate
+      def operation_multiplier(request)
+        return 100 if delete_all?(request)
+
+        case request.operation
+        when :upsert
+          collection_size(request.params[:vectors])
+        when :fetch, :delete
+          collection_size(request.params[:ids])
+        else
+          1 # Includes :query and all other operations
+        end
+      end
+
+      # Check if request is a delete_all operation
+      #
+      # @param request [Request] The request object
+      # @return [Boolean]
+      def delete_all?(request)
+        request.operation == :delete && request.params[:delete_all]
+      end
+
+      # Safely compute collection size with a default of 1
+      #
+      # @param collection [Enumerable, nil]
+      # @return [Integer]
+      def collection_size(collection)
+        collection&.size || 1
+      end
+    end
+  end
+end

data/lib/vectra/middleware/instrumentation.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Instrumentation middleware for metrics and monitoring
+    #
+    # Emits instrumentation events for all operations, compatible with
+    # Vectra's existing instrumentation system.
+    #
+    # @example Enable instrumentation middleware
+    #   Vectra::Client.use Vectra::Middleware::Instrumentation
+    #
+    # @example With custom event handler
+    #   Vectra.on_operation do |event|
+    #     puts "Operation: #{event[:operation]}, Duration: #{event[:duration_ms]}ms"
+    #   end
+    #
+    #   Vectra::Client.use Vectra::Middleware::Instrumentation
+    #
+    class Instrumentation < Base
+      def call(request, app)
+        start_time = Time.now
+
+        response = app.call(request)
+
+        duration_ms = ((Time.now - start_time) * 1000).round(2)
+
+        # Emit instrumentation event
+        Vectra::Instrumentation.instrument(
+          operation: request.operation,
+          provider: request.provider,
+          index: request.index,
+          namespace: request.namespace,
+          duration_ms: duration_ms,
+          success: response.success?,
+          error: response.error&.class&.name,
+          metadata: response.metadata
+        )
+
+        response
+      end
+    end
+  end
+end

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, :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/version.rb

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

data/lib/vectra.rb

@@ -18,6 +18,15 @@ require_relative "vectra/health_check"
 require_relative "vectra/credential_rotation"
 require_relative "vectra/audit_log"
 require_relative "vectra/active_record"
+require_relative "vectra/middleware/request"
+require_relative "vectra/middleware/response"
+require_relative "vectra/middleware/base"
+require_relative "vectra/middleware/stack"
+require_relative "vectra/middleware/logging"
+require_relative "vectra/middleware/retry"
+require_relative "vectra/middleware/instrumentation"
+require_relative "vectra/middleware/pii_redaction"
+require_relative "vectra/middleware/cost_tracker"
 require_relative "vectra/providers/base"
 require_relative "vectra/providers/pinecone"
 require_relative "vectra/providers/qdrant"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.1.0
 platform: ruby
 authors:
 - Mijo Kristo
@@ -268,6 +268,7 @@ files:
 - docs/guides/faq.md
 - docs/guides/getting-started.md
 - docs/guides/installation.md
+- docs/guides/middleware.md
 - docs/guides/monitoring.md
 - docs/guides/performance.md
 - docs/guides/rails-integration.md
@@ -294,6 +295,7 @@ files:
 - examples/grafana-dashboard.json
 - examples/grafana-setup.md
 - examples/instrumentation_demo.rb
+- examples/middleware_demo.rb
 - examples/prometheus-exporter.rb
 - lib/generators/vectra/index_generator.rb
 - lib/generators/vectra/install_generator.rb
@@ -316,6 +318,15 @@ files:
 - lib/vectra/instrumentation/new_relic.rb
 - lib/vectra/instrumentation/sentry.rb
 - lib/vectra/logging.rb
+- lib/vectra/middleware/base.rb
+- lib/vectra/middleware/cost_tracker.rb
+- lib/vectra/middleware/instrumentation.rb
+- lib/vectra/middleware/logging.rb
+- lib/vectra/middleware/pii_redaction.rb
+- lib/vectra/middleware/request.rb
+- lib/vectra/middleware/response.rb
+- lib/vectra/middleware/retry.rb
+- lib/vectra/middleware/stack.rb
 - lib/vectra/pool.rb
 - lib/vectra/providers/base.rb
 - lib/vectra/providers/memory.rb