vectra-client 0.1.2

data/lib/vectra/query_result.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Represents results from a vector query
+  #
+  # @example Working with query results
+  #   results = client.query(index: 'my-index', vector: [0.1, 0.2], top_k: 5)
+  #   results.each do |match|
+  #     puts "ID: #{match.id}, Score: #{match.score}"
+  #   end
+  #
+  class QueryResult
+    include Enumerable
+
+    attr_reader :matches, :namespace, :usage
+
+    # Initialize a new QueryResult
+    #
+    # @param matches [Array<Match>] array of match results
+    # @param namespace [String, nil] the namespace queried
+    # @param usage [Hash, nil] usage statistics from the provider
+    def initialize(matches: [], namespace: nil, usage: nil)
+      @matches = matches.map { |m| m.is_a?(Match) ? m : Match.new(**m.transform_keys(&:to_sym)) }
+      @namespace = namespace
+      @usage = usage
+    end
+
+    # Iterate over matches
+    #
+    # @yield [Match] each match
+    def each(&)
+      matches.each(&)
+    end
+
+    # Get the number of matches
+    #
+    # @return [Integer]
+    def size
+      matches.size
+    end
+
+    alias length size
+    alias count size
+
+    # Check if there are no matches
+    #
+    # @return [Boolean]
+    def empty?
+      matches.empty?
+    end
+
+    # Get the first match
+    #
+    # @return [Match, nil]
+    def first
+      matches.first
+    end
+
+    # Get the last match
+    #
+    # @return [Match, nil]
+    def last
+      matches.last
+    end
+
+    # Get match by index
+    #
+    # @param index [Integer]
+    # @return [Match, nil]
+    def [](index)
+      matches[index]
+    end
+
+    # Get all vector IDs
+    #
+    # @return [Array<String>]
+    def ids
+      matches.map(&:id)
+    end
+
+    # Get all scores
+    #
+    # @return [Array<Float>]
+    def scores
+      matches.map(&:score)
+    end
+
+    # Get the highest score
+    #
+    # @return [Float, nil]
+    def max_score
+      scores.max
+    end
+
+    # Get the lowest score
+    #
+    # @return [Float, nil]
+    def min_score
+      scores.min
+    end
+
+    # Filter matches by minimum score
+    #
+    # @param min_score [Float] minimum score threshold
+    # @return [QueryResult] new result with filtered matches
+    def above_score(min_score)
+      filtered = matches.select { |m| m.score >= min_score }
+      QueryResult.new(matches: filtered, namespace: namespace, usage: usage)
+    end
+
+    # Convert to array of hashes
+    #
+    # @return [Array<Hash>]
+    def to_a
+      matches.map(&:to_h)
+    end
+
+    # Convert to hash
+    #
+    # @return [Hash]
+    def to_h
+      {
+        matches: to_a,
+        namespace: namespace,
+        usage: usage
+      }.compact
+    end
+
+    # Create QueryResult from provider response
+    #
+    # @param data [Hash] raw response data
+    # @return [QueryResult]
+    def self.from_response(data)
+      data = data.transform_keys(&:to_sym)
+      matches = (data[:matches] || []).map do |match|
+        Match.from_hash(match)
+      end
+
+      new(
+        matches: matches,
+        namespace: data[:namespace],
+        usage: data[:usage]
+      )
+    end
+
+    # String representation
+    #
+    # @return [String]
+    def to_s
+      "#<Vectra::QueryResult matches=#{size} namespace=#{namespace.inspect}>"
+    end
+
+    alias inspect to_s
+  end
+
+  # Represents a single match from a query
+  class Match
+    attr_reader :id, :score, :values, :metadata, :sparse_values
+
+    # Initialize a new Match
+    #
+    # @param id [String] vector ID
+    # @param score [Float] similarity score
+    # @param values [Array<Float>, nil] vector values (if requested)
+    # @param metadata [Hash, nil] vector metadata (if requested)
+    # @param sparse_values [Hash, nil] sparse vector values
+    def initialize(id:, score:, values: nil, metadata: nil, sparse_values: nil)
+      @id = id.to_s
+      @score = score.to_f
+      @values = values
+      @metadata = metadata&.transform_keys(&:to_s) || {}
+      @sparse_values = sparse_values
+    end
+
+    # Check if values are included
+    #
+    # @return [Boolean]
+    def values?
+      !values.nil?
+    end
+
+    # Check if metadata is included
+    #
+    # @return [Boolean]
+    def metadata?
+      !metadata.empty?
+    end
+
+    # Get metadata value by key
+    #
+    # @param key [String, Symbol] metadata key
+    # @return [Object, nil]
+    def [](key)
+      metadata[key.to_s]
+    end
+
+    # Convert to Vector object
+    #
+    # @return [Vector]
+    # @raise [Error] if values are not included
+    def to_vector
+      raise Error, "Vector values not included in query result" unless values?
+
+      Vector.new(
+        id: id,
+        values: values,
+        metadata: metadata,
+        sparse_values: sparse_values
+      )
+    end
+
+    # Convert to hash
+    #
+    # @return [Hash]
+    def to_h
+      hash = { id: id, score: score }
+      hash[:values] = values if values?
+      hash[:metadata] = metadata if metadata?
+      hash[:sparse_values] = sparse_values if sparse_values
+      hash
+    end
+
+    # Create Match from hash
+    #
+    # @param hash [Hash]
+    # @return [Match]
+    def self.from_hash(hash)
+      hash = hash.transform_keys(&:to_sym)
+      new(
+        id: hash[:id],
+        score: hash[:score],
+        values: hash[:values],
+        metadata: hash[:metadata],
+        sparse_values: hash[:sparse_values]
+      )
+    end
+
+    # Check equality
+    #
+    # @param other [Match]
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(Match)
+
+      id == other.id && score == other.score
+    end
+
+    # String representation
+    #
+    # @return [String]
+    def to_s
+      "#<Vectra::Match id=#{id.inspect} score=#{score.round(4)}>"
+    end
+
+    alias inspect to_s
+  end
+end

data/lib/vectra/vector.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Represents a vector with its associated data
+  #
+  # @example Create a vector
+  #   vector = Vectra::Vector.new(
+  #     id: 'vec1',
+  #     values: [0.1, 0.2, 0.3],
+  #     metadata: { text: 'Hello world', category: 'greeting' }
+  #   )
+  #
+  class Vector
+    attr_reader :id, :values, :metadata, :sparse_values
+
+    # Initialize a new Vector
+    #
+    # @param id [String] unique identifier for the vector
+    # @param values [Array<Float>] the vector embedding values
+    # @param metadata [Hash] optional metadata associated with the vector
+    # @param sparse_values [Hash] optional sparse vector values
+    def initialize(id:, values:, metadata: nil, sparse_values: nil)
+      @id = validate_id!(id)
+      @values = validate_values!(values)
+      @metadata = metadata&.transform_keys(&:to_s) || {}
+      @sparse_values = sparse_values
+    end
+
+    # Get the dimension of the vector
+    #
+    # @return [Integer]
+    def dimension
+      values.length
+    end
+
+    # Check if vector has metadata
+    #
+    # @return [Boolean]
+    def metadata?
+      !metadata.empty?
+    end
+
+    # Check if vector has sparse values
+    #
+    # @return [Boolean]
+    def sparse?
+      !sparse_values.nil? && !sparse_values.empty?
+    end
+
+    # Convert vector to hash for API requests
+    #
+    # @return [Hash]
+    def to_h
+      hash = {
+        id: id,
+        values: values
+      }
+      hash[:metadata] = metadata unless metadata.empty?
+      hash[:sparse_values] = sparse_values if sparse?
+      hash
+    end
+
+    alias to_hash to_h
+
+    # Create a Vector from a hash
+    #
+    # @param hash [Hash] hash containing vector data
+    # @return [Vector]
+    def self.from_hash(hash)
+      hash = hash.transform_keys(&:to_sym)
+      new(
+        id: hash[:id],
+        values: hash[:values],
+        metadata: hash[:metadata],
+        sparse_values: hash[:sparse_values]
+      )
+    end
+
+    # Calculate cosine similarity with another vector
+    #
+    # @param other [Vector, Array<Float>] the other vector
+    # @return [Float] similarity score between -1 and 1
+    def cosine_similarity(other)
+      other_values = other.is_a?(Vector) ? other.values : other
+
+      raise ArgumentError, "Vectors must have the same dimension" if values.length != other_values.length
+
+      dot_product = values.zip(other_values).sum { |a, b| a * b }
+      magnitude_a = Math.sqrt(values.sum { |v| v**2 })
+      magnitude_b = Math.sqrt(other_values.sum { |v| v**2 })
+
+      return 0.0 if magnitude_a.zero? || magnitude_b.zero?
+
+      dot_product / (magnitude_a * magnitude_b)
+    end
+
+    # Calculate Euclidean distance to another vector
+    #
+    # @param other [Vector, Array<Float>] the other vector
+    # @return [Float] distance (0 = identical)
+    def euclidean_distance(other)
+      other_values = other.is_a?(Vector) ? other.values : other
+
+      raise ArgumentError, "Vectors must have the same dimension" if values.length != other_values.length
+
+      Math.sqrt(values.zip(other_values).sum { |a, b| (a - b)**2 })
+    end
+
+    # Check equality with another vector
+    #
+    # @param other [Vector] the other vector
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(Vector)
+
+      id == other.id && values == other.values && metadata == other.metadata
+    end
+
+    alias eql? ==
+
+    def hash
+      [id, values, metadata].hash
+    end
+
+    # String representation
+    #
+    # @return [String]
+    def to_s
+      "#<Vectra::Vector id=#{id.inspect} dimension=#{dimension} metadata_keys=#{metadata.keys}>"
+    end
+
+    alias inspect to_s
+
+    private
+
+    def validate_id!(id)
+      raise ValidationError, "Vector ID cannot be nil" if id.nil?
+      raise ValidationError, "Vector ID must be a string" unless id.is_a?(String) || id.is_a?(Symbol)
+
+      id.to_s
+    end
+
+    def validate_values!(values)
+      raise ValidationError, "Vector values cannot be nil" if values.nil?
+      raise ValidationError, "Vector values must be an array" unless values.is_a?(Array)
+      raise ValidationError, "Vector values cannot be empty" if values.empty?
+
+      unless values.all? { |v| v.is_a?(Numeric) }
+        raise ValidationError, "All vector values must be numeric"
+      end
+
+      values.map(&:to_f)
+    end
+  end
+end

data/lib/vectra/version.rb

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

data/lib/vectra.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "vectra/version"
+require_relative "vectra/errors"
+require_relative "vectra/configuration"
+require_relative "vectra/vector"
+require_relative "vectra/query_result"
+require_relative "vectra/providers/base"
+require_relative "vectra/providers/pinecone"
+require_relative "vectra/providers/qdrant"
+require_relative "vectra/providers/weaviate"
+require_relative "vectra/providers/pgvector"
+require_relative "vectra/client"
+
+# Vectra - Unified Ruby client for vector databases
+#
+# Vectra provides a simple, unified interface to work with multiple
+# vector database providers including Pinecone, Qdrant, and Weaviate.
+#
+# @example Basic usage
+#   # Configure globally
+#   Vectra.configure do |config|
+#     config.provider = :pinecone
+#     config.api_key = ENV['PINECONE_API_KEY']
+#     config.environment = 'us-east-1'
+#   end
+#
+#   # Create a client
+#   client = Vectra::Client.new
+#
+#   # Upsert vectors
+#   client.upsert(
+#     index: 'my-index',
+#     vectors: [
+#       { id: 'vec1', values: [0.1, 0.2, 0.3], metadata: { text: 'Hello' } }
+#     ]
+#   )
+#
+#   # Query vectors
+#   results = client.query(
+#     index: 'my-index',
+#     vector: [0.1, 0.2, 0.3],
+#     top_k: 5
+#   )
+#
+#   # Process results
+#   results.each do |match|
+#     puts "ID: #{match.id}, Score: #{match.score}"
+#   end
+#
+# @see Vectra::Client
+# @see Vectra::Configuration
+#
+module Vectra
+  class << self
+    # Create a new client with the given options
+    #
+    # @param options [Hash] client options
+    # @return [Client]
+    def client(**options)
+      Client.new(**options)
+    end
+
+    # Shortcut to create a Pinecone client
+    #
+    # @param api_key [String] Pinecone API key
+    # @param environment [String] Pinecone environment
+    # @param options [Hash] additional options
+    # @return [Client]
+    def pinecone(api_key:, environment: nil, host: nil, **options)
+      Client.new(
+        provider: :pinecone,
+        api_key: api_key,
+        environment: environment,
+        host: host,
+        **options
+      )
+    end
+
+    # Shortcut to create a Qdrant client
+    #
+    # @param api_key [String] Qdrant API key
+    # @param host [String] Qdrant host URL
+    # @param options [Hash] additional options
+    # @return [Client]
+    def qdrant(api_key:, host:, **options)
+      Client.new(
+        provider: :qdrant,
+        api_key: api_key,
+        host: host,
+        **options
+      )
+    end
+
+    # Shortcut to create a Weaviate client
+    #
+    # @param api_key [String] Weaviate API key
+    # @param host [String] Weaviate host URL
+    # @param options [Hash] additional options
+    # @return [Client]
+    def weaviate(api_key:, host:, **options)
+      Client.new(
+        provider: :weaviate,
+        api_key: api_key,
+        host: host,
+        **options
+      )
+    end
+
+    # Shortcut to create a pgvector client
+    #
+    # @param connection_url [String] PostgreSQL connection URL (postgres://user:pass@host/db)
+    # @param host [String] PostgreSQL host (alternative to connection_url)
+    # @param password [String] PostgreSQL password (used with host)
+    # @param options [Hash] additional options
+    # @return [Client]
+    #
+    # @example With connection URL
+    #   Vectra.pgvector(connection_url: "postgres://user:pass@localhost/mydb")
+    #
+    # @example With host and password
+    #   Vectra.pgvector(host: "localhost", password: "secret")
+    #
+    def pgvector(connection_url: nil, host: nil, password: nil, **options)
+      Client.new(
+        provider: :pgvector,
+        api_key: password,
+        host: connection_url || host,
+        **options
+      )
+    end
+  end
+end