vectra-client 0.1.2

data/lib/vectra/client.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Unified client for vector database operations
+  #
+  # The Client class provides a unified interface to interact with various
+  # vector database providers. It automatically routes operations to the
+  # configured provider.
+  #
+  # @example Using global configuration
+  #   Vectra.configure do |config|
+  #     config.provider = :pinecone
+  #     config.api_key = ENV['PINECONE_API_KEY']
+  #     config.environment = 'us-east-1'
+  #   end
+  #
+  #   client = Vectra::Client.new
+  #   client.upsert(index: 'my-index', vectors: [...])
+  #
+  # @example Using instance configuration
+  #   client = Vectra::Client.new(
+  #     provider: :pinecone,
+  #     api_key: ENV['PINECONE_API_KEY'],
+  #     environment: 'us-east-1'
+  #   )
+  #
+  class Client
+    attr_reader :config, :provider
+
+    # Initialize a new Client
+    #
+    # @param provider [Symbol, nil] provider name (:pinecone, :qdrant, :weaviate)
+    # @param api_key [String, nil] API key
+    # @param environment [String, nil] environment/region
+    # @param host [String, nil] custom host URL
+    # @param options [Hash] additional options
+    def initialize(provider: nil, api_key: nil, environment: nil, host: nil, **options)
+      @config = build_config(provider, api_key, environment, host, options)
+      @config.validate!
+      @provider = build_provider
+    end
+
+    # Upsert vectors into an index
+    #
+    # @param index [String] the index/collection name
+    # @param vectors [Array<Hash, Vector>] vectors to upsert
+    # @param namespace [String, nil] optional namespace (provider-specific)
+    # @return [Hash] upsert response with :upserted_count
+    #
+    # @example Upsert vectors
+    #   client.upsert(
+    #     index: 'my-index',
+    #     vectors: [
+    #       { id: 'vec1', values: [0.1, 0.2, 0.3], metadata: { text: 'Hello' } },
+    #       { id: 'vec2', values: [0.4, 0.5, 0.6], metadata: { text: 'World' } }
+    #     ]
+    #   )
+    #
+    def upsert(index:, vectors:, namespace: nil)
+      validate_index!(index)
+      validate_vectors!(vectors)
+
+      provider.upsert(index: index, vectors: vectors, namespace: namespace)
+    end
+
+    # Query vectors by similarity
+    #
+    # @param index [String] the index/collection name
+    # @param vector [Array<Float>] query vector
+    # @param top_k [Integer] number of results to return (default: 10)
+    # @param namespace [String, nil] optional namespace
+    # @param filter [Hash, nil] metadata filter
+    # @param include_values [Boolean] include vector values in response
+    # @param include_metadata [Boolean] include metadata in response
+    # @return [QueryResult] query results
+    #
+    # @example Simple query
+    #   results = client.query(
+    #     index: 'my-index',
+    #     vector: [0.1, 0.2, 0.3],
+    #     top_k: 5
+    #   )
+    #
+    # @example Query with filter
+    #   results = client.query(
+    #     index: 'my-index',
+    #     vector: [0.1, 0.2, 0.3],
+    #     top_k: 10,
+    #     filter: { category: 'programming' }
+    #   )
+    #
+    def query(index:, vector:, top_k: 10, namespace: nil, filter: nil,
+              include_values: false, include_metadata: true)
+      validate_index!(index)
+      validate_query_vector!(vector)
+
+      provider.query(
+        index: index,
+        vector: vector,
+        top_k: top_k,
+        namespace: namespace,
+        filter: filter,
+        include_values: include_values,
+        include_metadata: include_metadata
+      )
+    end
+
+    # Fetch vectors by IDs
+    #
+    # @param index [String] the index/collection name
+    # @param ids [Array<String>] vector IDs to fetch
+    # @param namespace [String, nil] optional namespace
+    # @return [Hash<String, Vector>] hash of ID to Vector
+    #
+    # @example Fetch vectors
+    #   vectors = client.fetch(index: 'my-index', ids: ['vec1', 'vec2'])
+    #   vectors['vec1'].values # => [0.1, 0.2, 0.3]
+    #
+    def fetch(index:, ids:, namespace: nil)
+      validate_index!(index)
+      validate_ids!(ids)
+
+      provider.fetch(index: index, ids: ids, namespace: namespace)
+    end
+
+    # Update a vector's metadata or values
+    #
+    # @param index [String] the index/collection name
+    # @param id [String] vector ID
+    # @param metadata [Hash, nil] new metadata (merged with existing)
+    # @param values [Array<Float>, nil] new vector values
+    # @param namespace [String, nil] optional namespace
+    # @return [Hash] update response
+    #
+    # @example Update metadata
+    #   client.update(
+    #     index: 'my-index',
+    #     id: 'vec1',
+    #     metadata: { category: 'updated' }
+    #   )
+    #
+    def update(index:, id:, metadata: nil, values: nil, namespace: nil)
+      validate_index!(index)
+      validate_id!(id)
+
+      raise ValidationError, "Must provide metadata or values to update" if metadata.nil? && values.nil?
+
+      provider.update(
+        index: index,
+        id: id,
+        metadata: metadata,
+        values: values,
+        namespace: namespace
+      )
+    end
+
+    # Delete vectors
+    #
+    # @param index [String] the index/collection name
+    # @param ids [Array<String>, nil] vector IDs to delete
+    # @param namespace [String, nil] optional namespace
+    # @param filter [Hash, nil] delete by metadata filter
+    # @param delete_all [Boolean] delete all vectors in namespace
+    # @return [Hash] delete response
+    #
+    # @example Delete by IDs
+    #   client.delete(index: 'my-index', ids: ['vec1', 'vec2'])
+    #
+    # @example Delete by filter
+    #   client.delete(index: 'my-index', filter: { category: 'old' })
+    #
+    # @example Delete all
+    #   client.delete(index: 'my-index', delete_all: true)
+    #
+    def delete(index:, ids: nil, namespace: nil, filter: nil, delete_all: false)
+      validate_index!(index)
+
+      if ids.nil? && filter.nil? && !delete_all
+        raise ValidationError, "Must provide ids, filter, or delete_all"
+      end
+
+      provider.delete(
+        index: index,
+        ids: ids,
+        namespace: namespace,
+        filter: filter,
+        delete_all: delete_all
+      )
+    end
+
+    # List all indexes
+    #
+    # @return [Array<Hash>] list of index information
+    #
+    # @example
+    #   indexes = client.list_indexes
+    #   indexes.each { |idx| puts idx[:name] }
+    #
+    def list_indexes
+      provider.list_indexes
+    end
+
+    # Describe an index
+    #
+    # @param index [String] the index name
+    # @return [Hash] index details
+    #
+    # @example
+    #   info = client.describe_index(index: 'my-index')
+    #   puts info[:dimension]
+    #
+    def describe_index(index:)
+      validate_index!(index)
+      provider.describe_index(index: index)
+    end
+
+    # Get index statistics
+    #
+    # @param index [String] the index name
+    # @param namespace [String, nil] optional namespace
+    # @return [Hash] index statistics
+    #
+    # @example
+    #   stats = client.stats(index: 'my-index')
+    #   puts "Total vectors: #{stats[:total_vector_count]}"
+    #
+    def stats(index:, namespace: nil)
+      validate_index!(index)
+      provider.stats(index: index, namespace: namespace)
+    end
+
+    # Get the provider name
+    #
+    # @return [Symbol]
+    def provider_name
+      provider.provider_name
+    end
+
+    private
+
+    def build_config(provider_name, api_key, environment, host, options)
+      # Start with global config or new config
+      cfg = Vectra.configuration.dup
+
+      # Override with provided values
+      cfg.provider = provider_name if provider_name
+      cfg.api_key = api_key if api_key
+      cfg.environment = environment if environment
+      cfg.host = host if host
+      cfg.timeout = options[:timeout] if options[:timeout]
+      cfg.open_timeout = options[:open_timeout] if options[:open_timeout]
+      cfg.max_retries = options[:max_retries] if options[:max_retries]
+      cfg.retry_delay = options[:retry_delay] if options[:retry_delay]
+      cfg.logger = options[:logger] if options[:logger]
+
+      cfg
+    end
+
+    def build_provider
+      case config.provider
+      when :pinecone
+        Providers::Pinecone.new(config)
+      when :qdrant
+        Providers::Qdrant.new(config)
+      when :weaviate
+        Providers::Weaviate.new(config)
+      when :pgvector
+        Providers::Pgvector.new(config)
+      else
+        raise UnsupportedProviderError, "Provider '#{config.provider}' is not supported"
+      end
+    end
+
+    def validate_index!(index)
+      raise ValidationError, "Index name cannot be nil" if index.nil?
+      raise ValidationError, "Index name must be a string" unless index.is_a?(String)
+      raise ValidationError, "Index name cannot be empty" if index.empty?
+    end
+
+    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?
+    end
+
+    def validate_query_vector!(vector)
+      raise ValidationError, "Query vector cannot be nil" if vector.nil?
+      raise ValidationError, "Query vector must be an array" unless vector.is_a?(Array)
+      raise ValidationError, "Query vector cannot be empty" if vector.empty?
+    end
+
+    def validate_ids!(ids)
+      raise ValidationError, "IDs cannot be nil" if ids.nil?
+      raise ValidationError, "IDs must be an array" unless ids.is_a?(Array)
+      raise ValidationError, "IDs cannot be empty" if ids.empty?
+    end
+
+    def validate_id!(id)
+      raise ValidationError, "ID cannot be nil" if id.nil?
+      raise ValidationError, "ID must be a string" unless id.is_a?(String)
+      raise ValidationError, "ID cannot be empty" if id.empty?
+    end
+  end
+end

data/lib/vectra/configuration.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Configuration class for Vectra
+  #
+  # @example Configure Vectra globally
+  #   Vectra.configure do |config|
+  #     config.provider = :pinecone
+  #     config.api_key = ENV['PINECONE_API_KEY']
+  #     config.environment = 'us-east-1'
+  #   end
+  #
+  class Configuration
+    SUPPORTED_PROVIDERS = %i[pinecone qdrant weaviate pgvector].freeze
+
+    attr_accessor :api_key, :environment, :host, :timeout, :open_timeout,
+                  :max_retries, :retry_delay, :logger
+
+    attr_reader :provider
+
+    def initialize
+      @provider = nil
+      @api_key = nil
+      @environment = nil
+      @host = nil
+      @timeout = 30
+      @open_timeout = 10
+      @max_retries = 3
+      @retry_delay = 1
+      @logger = nil
+    end
+
+    # Set the provider
+    #
+    # @param value [Symbol, String] the provider name
+    # @raise [UnsupportedProviderError] if provider is not supported
+    def provider=(value)
+      provider_sym = value.to_sym
+
+      unless SUPPORTED_PROVIDERS.include?(provider_sym)
+        raise UnsupportedProviderError,
+              "Provider '#{value}' is not supported. " \
+              "Supported providers: #{SUPPORTED_PROVIDERS.join(', ')}"
+      end
+
+      @provider = provider_sym
+    end
+
+    # Validate the configuration
+    #
+    # @raise [ConfigurationError] if configuration is invalid
+    def validate!
+      raise ConfigurationError, "Provider must be configured" if provider.nil?
+      raise ConfigurationError, "API key must be configured" if api_key.nil? || api_key.empty?
+
+      validate_provider_specific!
+    end
+
+    # Check if configuration is valid
+    #
+    # @return [Boolean]
+    def valid?
+      validate!
+      true
+    rescue ConfigurationError
+      false
+    end
+
+    # Create a duplicate configuration
+    #
+    # @return [Configuration]
+    def dup
+      config = Configuration.new
+      config.instance_variable_set(:@provider, @provider)
+      config.api_key = @api_key
+      config.environment = @environment
+      config.host = @host
+      config.timeout = @timeout
+      config.open_timeout = @open_timeout
+      config.max_retries = @max_retries
+      config.retry_delay = @retry_delay
+      config.logger = @logger
+      config
+    end
+
+    # Convert configuration to hash
+    #
+    # @return [Hash]
+    def to_h
+      {
+        provider: provider,
+        api_key: api_key,
+        environment: environment,
+        host: host,
+        timeout: timeout,
+        open_timeout: open_timeout,
+        max_retries: max_retries,
+        retry_delay: retry_delay
+      }
+    end
+
+    private
+
+    def validate_provider_specific!
+      case provider
+      when :pinecone
+        validate_pinecone!
+      when :qdrant
+        validate_qdrant!
+      when :weaviate
+        validate_weaviate!
+      when :pgvector
+        validate_pgvector!
+      end
+    end
+
+    def validate_pinecone!
+      return unless environment.nil? && host.nil?
+
+      raise ConfigurationError,
+            "Pinecone requires either 'environment' or 'host' to be configured"
+    end
+
+    def validate_qdrant!
+      return unless host.nil?
+
+      raise ConfigurationError, "Qdrant requires 'host' to be configured"
+    end
+
+    def validate_weaviate!
+      return unless host.nil?
+
+      raise ConfigurationError, "Weaviate requires 'host' to be configured"
+    end
+
+    def validate_pgvector!
+      return unless host.nil?
+
+      raise ConfigurationError, "pgvector requires 'host' (connection URL or hostname) to be configured"
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    # Get the current configuration
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure Vectra
+    #
+    # @yield [Configuration] the configuration object
+    # @return [Configuration]
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    # Reset configuration to defaults
+    #
+    # @return [Configuration]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/vectra/errors.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Base error class for all Vectra errors
+  class Error < StandardError
+    attr_reader :original_error, :response
+
+    def initialize(message = nil, original_error: nil, response: nil)
+      @original_error = original_error
+      @response = response
+      super(message)
+    end
+  end
+
+  # Raised when configuration is invalid or missing
+  class ConfigurationError < Error; end
+
+  # Raised when authentication fails
+  class AuthenticationError < Error; end
+
+  # Raised when a resource is not found
+  class NotFoundError < Error; end
+
+  # Raised when rate limit is exceeded
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **kwargs)
+      @retry_after = retry_after
+      super(message, **kwargs)
+    end
+  end
+
+  # Raised when request validation fails
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message = nil, errors: [], **kwargs)
+      @errors = errors
+      super(message, **kwargs)
+    end
+  end
+
+  # Raised when there's a connection problem
+  class ConnectionError < Error; end
+
+  # Raised when the server returns an error
+  class ServerError < Error
+    attr_reader :status_code
+
+    def initialize(message = nil, status_code: nil, **kwargs)
+      @status_code = status_code
+      super(message, **kwargs)
+    end
+  end
+
+  # Raised when the provider is not supported
+  class UnsupportedProviderError < Error; end
+
+  # Raised when an operation times out
+  class TimeoutError < Error; end
+
+  # Raised when batch operation partially fails
+  class BatchError < Error
+    attr_reader :succeeded, :failed
+
+    def initialize(message = nil, succeeded: [], failed: [], **kwargs)
+      @succeeded = succeeded
+      @failed = failed
+      super(message, **kwargs)
+    end
+  end
+end