vectra-client 0.1.2

data/lib/vectra/providers/base.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module Vectra
+  module Providers
+    # Abstract base class for vector database providers
+    #
+    # All provider implementations must inherit from this class
+    # and implement the required methods.
+    #
+    class Base
+      attr_reader :config
+
+      # Initialize the provider
+      #
+      # @param config [Configuration] the configuration object
+      def initialize(config)
+        @config = config
+        validate_config!
+      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
+      # @return [Hash] upsert response
+      def upsert(index:, vectors:, namespace: nil)
+        raise NotImplementedError, "#{self.class} must implement #upsert"
+      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
+      # @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
+      def query(index:, vector:, top_k: 10, namespace: nil, filter: nil,
+                include_values: false, include_metadata: true)
+        raise NotImplementedError, "#{self.class} must implement #query"
+      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>] fetched vectors
+      def fetch(index:, ids:, namespace: nil)
+        raise NotImplementedError, "#{self.class} must implement #fetch"
+      end
+
+      # Update a vector's metadata
+      #
+      # @param index [String] the index/collection name
+      # @param id [String] vector ID
+      # @param metadata [Hash] new metadata
+      # @param namespace [String, nil] optional namespace
+      # @return [Hash] update response
+      def update(index:, id:, metadata:, namespace: nil)
+        raise NotImplementedError, "#{self.class} must implement #update"
+      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
+      # @return [Hash] delete response
+      def delete(index:, ids: nil, namespace: nil, filter: nil, delete_all: false)
+        raise NotImplementedError, "#{self.class} must implement #delete"
+      end
+
+      # List indexes/collections
+      #
+      # @return [Array<Hash>] list of indexes
+      def list_indexes
+        raise NotImplementedError, "#{self.class} must implement #list_indexes"
+      end
+
+      # Describe an index
+      #
+      # @param index [String] the index name
+      # @return [Hash] index details
+      def describe_index(index:)
+        raise NotImplementedError, "#{self.class} must implement #describe_index"
+      end
+
+      # Get index statistics
+      #
+      # @param index [String] the index name
+      # @param namespace [String, nil] optional namespace
+      # @return [Hash] index statistics
+      def stats(index:, namespace: nil)
+        raise NotImplementedError, "#{self.class} must implement #stats"
+      end
+
+      # Provider name
+      #
+      # @return [Symbol]
+      def provider_name
+        raise NotImplementedError, "#{self.class} must implement #provider_name"
+      end
+
+      protected
+
+      # Build HTTP connection with retry logic
+      #
+      # @param base_url [String] base URL for the API
+      # @param headers [Hash] request headers
+      # @return [Faraday::Connection]
+      def build_connection(base_url, headers = {})
+        Faraday.new(url: base_url) do |conn|
+          conn.request :json
+          conn.response :json, content_type: /\bjson$/
+
+          conn.request :retry, {
+            max: config.max_retries,
+            interval: config.retry_delay,
+            interval_randomness: 0.5,
+            backoff_factor: 2,
+            retry_statuses: [429, 500, 502, 503, 504],
+            exceptions: [
+              Faraday::TimeoutError,
+              Faraday::ConnectionFailed
+            ]
+          }
+
+          conn.headers = default_headers.merge(headers)
+          conn.options.timeout = config.timeout
+          conn.options.open_timeout = config.open_timeout
+
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      # Default headers for all requests
+      #
+      # @return [Hash]
+      def default_headers
+        {
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "User-Agent" => "vectra-ruby/#{Vectra::VERSION}"
+        }
+      end
+
+      # Normalize vectors for API request
+      #
+      # @param vectors [Array<Hash, Vector>] vectors to normalize
+      # @return [Array<Hash>]
+      def normalize_vectors(vectors)
+        vectors.map do |vec|
+          case vec
+          when Vector
+            vec.to_h
+          when Hash
+            normalize_vector_hash(vec)
+          else
+            raise ValidationError, "Vector must be a Hash or Vectra::Vector"
+          end
+        end
+      end
+
+      # Normalize a single vector hash
+      #
+      # @param hash [Hash] vector hash
+      # @return [Hash]
+      def normalize_vector_hash(hash)
+        hash = hash.transform_keys(&:to_sym)
+
+        result = {
+          id: hash[:id].to_s,
+          values: hash[:values].map(&:to_f)
+        }
+
+        result[:metadata] = hash[:metadata] if hash[:metadata]
+        result[:sparse_values] = hash[:sparse_values] if hash[:sparse_values]
+
+        result
+      end
+
+      # Handle API errors
+      #
+      # @param response [Faraday::Response] the response
+      # @raise [Error] appropriate error for the response
+      def handle_error(response)
+        status = response.status
+        body = response.body
+
+        error_message = extract_error_message(body)
+
+        case status
+        when 400
+          raise ValidationError.new(error_message, response: response)
+        when 401
+          raise AuthenticationError.new(error_message, response: response)
+        when 403
+          raise AuthenticationError.new("Access forbidden: #{error_message}", response: response)
+        when 404
+          raise NotFoundError.new(error_message, response: response)
+        when 429
+          retry_after = response.headers["retry-after"]&.to_i
+          raise RateLimitError.new(error_message, retry_after: retry_after, response: response)
+        when 500..599
+          raise ServerError.new(error_message, status_code: status, response: response)
+        else
+          raise Error.new("Request failed with status #{status}: #{error_message}", response: response)
+        end
+      end
+
+      # Extract error message from response body
+      #
+      # @param body [Hash, String, nil] response body
+      # @return [String]
+      def extract_error_message(body)
+        case body
+        when Hash
+          body["message"] || body["error"] || body.to_s
+        when String
+          body
+        else
+          "Unknown error"
+        end
+      end
+
+      # Log debug information
+      #
+      # @param message [String] message to log
+      # @param data [Hash] optional data to log
+      def log_debug(message, data = nil)
+        return unless config.logger
+
+        config.logger.debug("[Vectra] #{message}")
+        config.logger.debug("[Vectra] #{data.inspect}") if data
+      end
+
+      # Log error information
+      #
+      # @param message [String] message to log
+      # @param error [Exception, nil] optional error
+      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
+      end
+
+      private
+
+      def validate_config!
+        config.validate!
+      end
+    end
+  end
+end

data/lib/vectra/providers/pgvector/connection.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Providers
+    class Pgvector < Base
+      # Connection management for pgvector provider
+      module Connection
+        private
+
+        # Get or create database connection
+        def connection
+          @connection ||= begin
+            require "pg"
+
+            conn_params = parse_connection_params
+            PG.connect(conn_params)
+          end
+        end
+
+        # Parse connection parameters from config
+        def parse_connection_params
+          if config.host&.start_with?("postgres://", "postgresql://")
+            { conninfo: config.host }
+          else
+            {
+              host: config.host || "localhost",
+              port: config.environment&.to_i || 5432,
+              dbname: extract_database_name,
+              user: extract_username,
+              password: config.api_key
+            }.compact
+          end
+        end
+
+        # Extract database name from host or use default
+        def extract_database_name
+          if config.host&.include?("/")
+            config.host.split("/").last
+          else
+            "postgres"
+          end
+        end
+
+        # Extract username
+        def extract_username
+          ENV.fetch("PGUSER", "postgres")
+        end
+
+        # Execute SQL with parameters
+        def execute(sql, params = [])
+          log_debug("Executing SQL", { sql: sql, params: params })
+          connection.exec_params(sql, params)
+        rescue PG::Error => e
+          handle_pg_error(e)
+        end
+
+        # Handle PostgreSQL errors
+        def handle_pg_error(error)
+          case error
+          when PG::UndefinedTable
+            raise NotFoundError, "not found"
+          when PG::InvalidPassword
+            raise AuthenticationError, "authentication failed"
+          when PG::ConnectionBad
+            raise ConnectionError, "connection failed"
+          when PG::UniqueViolation, PG::CheckViolation
+            raise ValidationError, error.message
+          else
+            raise ServerError.new(error.message, status_code: 500)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vectra/providers/pgvector/index_management.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Providers
+    class Pgvector < Base
+      # Index management methods for pgvector provider
+      module IndexManagement
+        INDEX_OPS = {
+          "cosine" => "vector_cosine_ops",
+          "euclidean" => "vector_l2_ops",
+          "inner_product" => "vector_ip_ops"
+        }.freeze
+
+        # Create a new index (table with vector column)
+        def create_index(name:, dimension:, metric: DEFAULT_METRIC)
+          validate_metric!(metric)
+          create_table_with_vector(name, dimension)
+          create_ivfflat_index(name, metric)
+          store_metric_comment(name, metric)
+
+          @table_cache[name] = { dimension: dimension, metric: metric }
+          log_debug("Created index #{name}")
+          describe_index(index: name)
+        end
+
+        # Delete an index (drop table)
+        def delete_index(name:)
+          execute("DROP TABLE IF EXISTS #{quote_ident(name)} CASCADE")
+          @table_cache.delete(name)
+          log_debug("Deleted index #{name}")
+          { deleted: true }
+        end
+
+        private
+
+        # Validate metric type
+        def validate_metric!(metric)
+          return if DISTANCE_FUNCTIONS.key?(metric)
+
+          raise ValidationError, "Invalid metric '#{metric}'. Supported: #{DISTANCE_FUNCTIONS.keys.join(', ')}"
+        end
+
+        # Extract dimension from vector type string
+        def extract_dimension_from_type(type_info)
+          match = type_info.match(/vector\((\d+)\)/)
+          return nil unless match
+
+          match.captures.first.to_i
+        end
+
+        # Create table with vector column
+        def create_table_with_vector(name, dimension)
+          execute("CREATE EXTENSION IF NOT EXISTS vector")
+
+          sql = <<~SQL
+            CREATE TABLE IF NOT EXISTS #{quote_ident(name)} (
+              id TEXT PRIMARY KEY,
+              embedding vector(#{dimension.to_i}),
+              metadata JSONB DEFAULT '{}',
+              namespace TEXT DEFAULT '',
+              created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+          SQL
+          execute(sql)
+        end
+
+        # Create IVFFlat index for similarity search
+        def create_ivfflat_index(name, metric)
+          index_op = INDEX_OPS[metric]
+          idx_name = "#{name}_embedding_idx"
+          idx_sql = <<~SQL
+            CREATE INDEX IF NOT EXISTS #{quote_ident(idx_name)}
+            ON #{quote_ident(name)}
+            USING ivfflat (embedding #{index_op})
+            WITH (lists = 100)
+          SQL
+
+          execute(idx_sql)
+        rescue PG::Error => e
+          log_debug("Index creation deferred: #{e.message}")
+        end
+
+        # Store metric in table comment
+        def store_metric_comment(name, metric)
+          execute("COMMENT ON TABLE #{quote_ident(name)} IS #{escape_literal("vectra:metric=#{metric}")}")
+        end
+
+        # Ensure table exists
+        def ensure_table_exists!(index)
+          return if @table_cache.key?(index)
+
+          sql = <<~SQL
+            SELECT EXISTS (
+              SELECT FROM information_schema.tables
+              WHERE table_schema = 'public' AND table_name = $1
+            )
+          SQL
+
+          result = execute(sql, [index])
+          exists_value = result.first["exists"]
+          exists = [true, "t"].include?(exists_value)
+
+          raise NotFoundError, "Index '#{index}' not found" unless exists
+
+          @table_cache[index] = true
+        end
+
+        # Get metric for a table from stored comment
+        def table_metric(index)
+          return @table_cache.dig(index, :metric) if @table_cache[index].is_a?(Hash)
+
+          sql = "SELECT obj_description($1::regclass, 'pg_class') as comment"
+          result = execute(sql, [index])
+          comment = result.first&.fetch("comment", nil)
+
+          metric = comment&.include?("vectra:metric=") ? comment.match(/vectra:metric=(\w+)/)&.captures&.first : nil
+          metric || DEFAULT_METRIC
+        end
+      end
+    end
+  end
+end

data/lib/vectra/providers/pgvector/sql_helpers.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Providers
+    class Pgvector < Base
+      # SQL helper methods for pgvector provider
+      module SqlHelpers
+        private
+
+        # Quote identifier to prevent SQL injection
+        def quote_ident(name)
+          connection.quote_ident(name)
+        end
+
+        # Escape literal string
+        def escape_literal(str)
+          connection.escape_literal(str)
+        end
+
+        # Format vector for PostgreSQL
+        def format_vector(values)
+          "[#{values.map(&:to_f).join(',')}]"
+        end
+
+        # Parse vector from PostgreSQL string format
+        def parse_vector(str)
+          return nil unless str
+
+          str.gsub(/[\[\]]/, "").split(",").map(&:to_f)
+        end
+
+        # Parse JSON from PostgreSQL
+        def parse_json(str)
+          return {} unless str
+
+          case str
+          when String
+            JSON.parse(str)
+          when Hash
+            str
+          else
+            {}
+          end
+        rescue JSON::ParserError
+          {}
+        end
+
+        # Build SQL for vector similarity query
+        def build_query_sql(index:, vector_literal:, distance_op:, top_k:,
+                            namespace:, filter:, include_values:, include_metadata:)
+          select_cols = build_select_columns(vector_literal, distance_op, include_values, include_metadata)
+          where_clauses = build_where_clauses(namespace, filter)
+
+          sql = "SELECT #{select_cols.join(', ')} FROM #{quote_ident(index)}"
+          sql += " WHERE #{where_clauses.join(' AND ')}" if where_clauses.any?
+          sql += " ORDER BY embedding #{distance_op} '#{vector_literal}'::vector"
+          sql += " LIMIT #{top_k.to_i}"
+          sql
+        end
+
+        # Build SELECT columns for query
+        def build_select_columns(vector_literal, distance_op, include_values, include_metadata)
+          cols = ["id", "1 - (embedding #{distance_op} '#{vector_literal}'::vector) as score"]
+          cols << "embedding" if include_values
+          cols << "metadata" if include_metadata
+          cols
+        end
+
+        # Build WHERE clauses for query
+        def build_where_clauses(namespace, filter)
+          clauses = []
+          clauses << "namespace = #{escape_literal(namespace)}" if namespace
+
+          filter&.each do |key, value|
+            json_path = "metadata->>#{escape_literal(key.to_s)}"
+            clauses << "#{json_path} = #{escape_literal(value.to_s)}"
+          end
+
+          clauses
+        end
+
+        # Build match hash from database row
+        def build_match_from_row(row, include_values, include_metadata)
+          match = { id: row["id"], score: row["score"].to_f }
+          match[:values] = parse_vector(row["embedding"]) if include_values && row["embedding"]
+          match[:metadata] = parse_json(row["metadata"]) if include_metadata && row["metadata"]
+          match
+        end
+
+        # Build SQL for filter-based delete
+        def build_filter_delete_sql(index, filter, namespace)
+          sql = "DELETE FROM #{quote_ident(index)} WHERE "
+          clauses = []
+          params = []
+          param_idx = 1
+
+          filter.each do |key, value|
+            clauses << "metadata->>$#{param_idx} = $#{param_idx + 1}"
+            params << key.to_s
+            params << value.to_s
+            param_idx += 2
+          end
+
+          if namespace
+            clauses << "namespace = $#{param_idx}"
+            params << namespace
+          end
+
+          sql += clauses.join(" AND ")
+          [sql, params]
+        end
+      end
+    end
+  end
+end