vectra-client 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23e0684b20e30c7083b21676f50611b82c2926baec2cd2596a02aa9d0f1524b2
-  data.tar.gz: 892a0094e23003e7c4647a931dca2b785c243439bad35d3511391df0b3275587
+  metadata.gz: 6c00aee137978894b5722853a5aa6419c76a4613fd07e7b772df83c0ffddcebd
+  data.tar.gz: 92f2e588d62520f695d59feaf74d6e1787efc8c1044cf92a8cf94251dcd9ce3a
 SHA512:
-  metadata.gz: 356585c134240dc3b36734f85f3a68965ee18f16dfe1437737628d1c8b9c0c9fcbaca11e7092e1328501fd861f1e1c297a8bad38197a1b0033a9af5159ddb075
-  data.tar.gz: 0abf8ee4bf16c01065db7dad529ff3da125a0f4bb45a91be19a94842405fdfc8e8c86a9aed7ae153b68323e528111fbea13ffbb2888b1216b1b045cbf1937888
+  metadata.gz: df1fa8e851978d7167e55d1df5d8718a01923b533ea10d314c24a570f84c1440dcb41bcad20ab9226206d742f03b8f3deb8aaf34d327f63fe5744345a9827127
+  data.tar.gz: 0f10f1ffa2f782f018d94d9c24a2311662ee4256f7c68495d233eb018220a023df5732e2fb541d302624ac543928d957f6ed6adb6bf34efe50e31a1f231c7d54

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2025-01-08
+
+### Added
+
+- **Qdrant Provider** - Full Qdrant vector database support:
+  - Vector upsert, query, fetch, update, delete operations
+  - Collection management (create, list, describe, delete)
+  - Multiple similarity metrics: cosine, euclidean, dot product
+  - Namespace support via payload filtering
+  - Advanced metadata filtering with Qdrant operators ($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin)
+  - Automatic point ID hashing for string IDs
+  - Support for both local and cloud Qdrant instances
+  - Optional API key authentication for local deployments
+
+### Improved
+
+- Enhanced error handling with `Faraday::RetriableResponse` support
+- Configuration now allows optional API key for Qdrant and pgvector (local instances)
+- Better retry middleware integration across all providers
+
+### Provider Support
+
+- ✅ Pinecone - Fully implemented
+- ✅ pgvector (PostgreSQL) - Fully implemented
+- ✅ Qdrant - Fully implemented
+- 🚧 Weaviate - Stub implementation (planned for v0.3.0)
+
 ## [0.2.0] - 2025-01-08
 
 ### Added
@@ -49,13 +76,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated gemspec description to include pgvector
 - Added `pg` gem as development dependency
 
-### Provider Support
-
-- ✅ Pinecone - Fully implemented
-- ✅ pgvector (PostgreSQL) - Fully implemented
-- 🚧 Qdrant - Stub implementation (planned for v0.2.0)
-- 🚧 Weaviate - Stub implementation (planned for v0.3.0)
-
 ## [0.1.0] - 2024-XX-XX
 
 ### Added
@@ -89,13 +109,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Planned
 
-### [0.2.0]
-
-- Qdrant provider implementation
-- Enhanced error messages
-- Connection pooling
-- Improved retry strategies
-
 ### [0.3.0]
 
 - Weaviate provider implementation

data/README.md

@@ -24,7 +24,7 @@
 |----------|--------|---------|
 | [Pinecone](https://pinecone.io) | ✅ Fully Supported | v0.1.0 |
 | [PostgreSQL + pgvector](https://github.com/pgvector/pgvector) | ✅ Fully Supported | v0.1.1 |
-| [Qdrant](https://qdrant.tech) | 🚧 Planned | v0.2.0 |
+| [Qdrant](https://qdrant.tech) | ✅ Fully Supported | v0.2.1 |
 | [Weaviate](https://weaviate.io) | 🚧 Planned | v0.3.0 |
 
 ## Installation
@@ -87,6 +87,12 @@ client = Vectra.pgvector(
   connection_url: 'postgres://user:password@localhost/mydb'
 )
 
+# Shortcut for Qdrant
+client = Vectra.qdrant(
+  host: 'http://localhost:6333',        # Local Qdrant
+  api_key: ENV['QDRANT_API_KEY']        # Optional for local instances
+)
+
 # Generic client with options
 client = Vectra::Client.new(
   provider: :pinecone,
@@ -421,10 +427,10 @@ bundle exec rake docs
 - ✅ Namespace support for pgvector
 - ✅ IVFFlat index creation
 
-### v0.2.0
-- 🚧 Qdrant provider
-- 🚧 Enhanced error handling
-- 🚧 Connection pooling
+### v0.2.1
+- ✅ Qdrant provider (fully implemented)
+- ✅ Enhanced error handling
+- ✅ Improved retry middleware
 
 ### v0.3.0
 - 🚧 Weaviate provider

data/Rakefile

@@ -34,7 +34,7 @@ task :changelog do
 end
 
 desc "Bump version to VERSION"
-task :bump_version, [:version] do |t, args|
+task :bump_version, [:version] do |_t, args|
   version = args[:version]
   raise "Version required: rake bump_version[1.2.3]" unless version
 

data/lib/vectra/configuration.rb

@@ -56,7 +56,11 @@ module Vectra
     # @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?
+
+      # API key is optional for some providers (Qdrant local, pgvector)
+      if !api_key_optional_provider? && (api_key.nil? || api_key.empty?)
+        raise ConfigurationError, "API key must be configured"
+      end
 
       validate_provider_specific!
     end
@@ -106,6 +110,11 @@ module Vectra
 
     private
 
+    # Providers that don't require API key (local instances)
+    def api_key_optional_provider?
+      %i[qdrant pgvector].include?(provider)
+    end
+
     def validate_provider_specific!
       case provider
       when :pinecone

data/lib/vectra/providers/base.rb

@@ -218,6 +218,16 @@ module Vectra
         end
       end
 
+      # Handle Faraday::RetriableResponse from retry middleware
+      # This is raised when all retries are exhausted
+      #
+      # @param exception [Faraday::RetriableResponse] the exception
+      # @raise [Error] appropriate error for the response
+      def handle_retriable_response(exception)
+        response = exception.response
+        handle_error(response)
+      end
+
       # Extract error message from response body
       #
       # @param body [Hash, String, nil] response body

data/lib/vectra/providers/qdrant.rb

@@ -2,47 +2,434 @@
 
 module Vectra
   module Providers
-    # Qdrant vector database provider (planned for v0.2.0)
+    # Qdrant vector database provider
     #
-    # @note This provider is not yet implemented
+    # Qdrant is an open-source vector similarity search engine with extended filtering support.
     #
+    # @example Basic usage
+    #   Vectra.configure do |config|
+    #     config.provider = :qdrant
+    #     config.api_key = ENV['QDRANT_API_KEY']
+    #     config.host = 'https://your-cluster.qdrant.io'
+    #   end
+    #
+    #   client = Vectra::Client.new
+    #   client.upsert(index: 'my-collection', vectors: [...])
+    #
+    # rubocop:disable Metrics/ClassLength
     class Qdrant < Base
+      # @see Base#provider_name
       def provider_name
         :qdrant
       end
 
+      # @see Base#upsert
       def upsert(index:, vectors:, namespace: nil)
-        raise NotImplementedError, "Qdrant provider is planned for v0.2.0"
+        normalized = normalize_vectors(vectors)
+
+        points = normalized.map do |vec|
+          point = {
+            id: generate_point_id(vec[:id]),
+            vector: vec[:values]
+          }
+
+          payload = vec[:metadata] || {}
+          payload["_namespace"] = namespace if namespace
+          point[:payload] = payload unless payload.empty?
+
+          point
+        end
+
+        body = {
+          points: points
+        }
+
+        response = with_error_handling { connection.put("/collections/#{index}/points", body) }
+
+        if response.success?
+          log_debug("Upserted #{normalized.size} vectors to #{index}")
+          { upserted_count: normalized.size }
+        else
+          handle_error(response)
+        end
       end
 
+      # @see Base#query
       def query(index:, vector:, top_k: 10, namespace: nil, filter: nil,
                 include_values: false, include_metadata: true)
-        raise NotImplementedError, "Qdrant provider is planned for v0.2.0"
+        body = {
+          vector: vector.map(&:to_f),
+          limit: top_k,
+          with_vector: include_values,
+          with_payload: include_metadata
+        }
+
+        # Build filter with namespace if provided
+        qdrant_filter = build_filter(filter, namespace)
+        body[:filter] = qdrant_filter if qdrant_filter
+
+        response = with_error_handling { connection.post("/collections/#{index}/points/search", body) }
+
+        if response.success?
+          matches = transform_search_results(response.body["result"] || [])
+          log_debug("Query returned #{matches.size} results")
+
+          QueryResult.from_response(
+            matches: matches,
+            namespace: namespace
+          )
+        else
+          handle_error(response)
+        end
       end
 
-      def fetch(index:, ids:, namespace: nil)
-        raise NotImplementedError, "Qdrant provider is planned for v0.2.0"
+      # @see Base#fetch
+      def fetch(index:, ids:, namespace: nil) # rubocop:disable Lint/UnusedMethodArgument
+        point_ids = ids.map { |id| generate_point_id(id) }
+
+        body = {
+          ids: point_ids,
+          with_vector: true,
+          with_payload: true
+        }
+
+        response = with_error_handling { connection.post("/collections/#{index}/points", body) }
+
+        if response.success?
+          vectors = {}
+          (response.body["result"] || []).each do |point|
+            original_id = extract_original_id(point["id"])
+            vectors[original_id] = Vector.new(
+              id: original_id,
+              values: point["vector"],
+              metadata: clean_payload(point["payload"])
+            )
+          end
+          vectors
+        else
+          handle_error(response)
+        end
       end
 
-      def update(index:, id:, metadata:, namespace: nil)
-        raise NotImplementedError, "Qdrant provider is planned for v0.2.0"
+      # @see Base#update
+      def update(index:, id:, metadata: nil, values: nil, namespace: nil)
+        point_id = generate_point_id(id)
+
+        # Update payload (metadata) if provided
+        if metadata
+          payload = metadata.dup
+          payload["_namespace"] = namespace if namespace
+
+          payload_body = {
+            points: [point_id],
+            payload: payload
+          }
+
+          response = with_error_handling { connection.post("/collections/#{index}/points/payload", payload_body) }
+          handle_error(response) unless response.success?
+        end
+
+        # Update vector if provided
+        if values
+          vector_body = {
+            points: [
+              {
+                id: point_id,
+                vector: values.map(&:to_f)
+              }
+            ]
+          }
+
+          response = with_error_handling { connection.put("/collections/#{index}/points", vector_body) }
+          handle_error(response) unless response.success?
+        end
+
+        log_debug("Updated vector #{id}")
+        { updated: true }
       end
 
+      # @see Base#delete
       def delete(index:, ids: nil, namespace: nil, filter: nil, delete_all: false)
-        raise NotImplementedError, "Qdrant provider is planned for v0.2.0"
+        if delete_all
+          # Delete all points in collection
+          body = { filter: {} }
+        elsif ids
+          # Delete by IDs
+          point_ids = ids.map { |id| generate_point_id(id) }
+          body = { points: point_ids }
+        elsif filter || namespace
+          # Delete by filter
+          body = { filter: build_filter(filter, namespace) }
+        else
+          raise ValidationError, "Must specify ids, filter, or delete_all"
+        end
+
+        response = with_error_handling { connection.post("/collections/#{index}/points/delete", body) }
+
+        if response.success?
+          log_debug("Deleted vectors from #{index}")
+          { deleted: true }
+        else
+          handle_error(response)
+        end
       end
 
+      # @see Base#list_indexes
       def list_indexes
-        raise NotImplementedError, "Qdrant provider is planned for v0.2.0"
+        response = with_error_handling { connection.get("/collections") }
+
+        if response.success?
+          (response.body["result"]&.dig("collections") || []).map do |col|
+            # Get collection info for each
+            info = describe_index(index: col["name"])
+            info
+          rescue StandardError
+            { name: col["name"], status: "unknown" }
+          end
+        else
+          handle_error(response)
+        end
       end
 
+      # @see Base#describe_index
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def describe_index(index:)
-        raise NotImplementedError, "Qdrant provider is planned for v0.2.0"
+        response = with_error_handling { connection.get("/collections/#{index}") }
+
+        if response.success?
+          result = response.body["result"]
+          config = result["config"]
+          params = config&.dig("params") || {}
+          vectors_config = params["vectors"] || {}
+
+          # Handle both named and unnamed vector configs
+          dimension = if vectors_config.is_a?(Hash) && vectors_config["size"]
+                        vectors_config["size"]
+                      elsif vectors_config.is_a?(Hash)
+                        vectors_config.values.first&.dig("size")
+                      end
+
+          distance = vectors_config["distance"] || vectors_config.values.first&.dig("distance")
+
+          {
+            name: index,
+            dimension: dimension,
+            metric: distance_to_metric(distance),
+            status: result["status"],
+            vectors_count: result["vectors_count"],
+            points_count: result["points_count"]
+          }
+        else
+          handle_error(response)
+        end
       end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+      # @see Base#stats
       def stats(index:, namespace: nil)
-        raise NotImplementedError, "Qdrant provider is planned for v0.2.0"
+        info = describe_index(index: index)
+
+        {
+          total_vector_count: info[:points_count] || info[:vectors_count] || 0,
+          dimension: info[:dimension],
+          status: info[:status],
+          namespaces: namespace ? { namespace => { vector_count: 0 } } : {}
+        }
+      end
+
+      # Create a new collection
+      #
+      # @param name [String] collection name
+      # @param dimension [Integer] vector dimension
+      # @param metric [String] similarity metric (cosine, euclidean, dot_product)
+      # @param on_disk [Boolean] store vectors on disk
+      # @return [Hash] created collection info
+      def create_index(name:, dimension:, metric: "cosine", on_disk: false)
+        body = {
+          vectors: {
+            size: dimension,
+            distance: metric_to_distance(metric),
+            on_disk: on_disk
+          }
+        }
+
+        response = with_error_handling { connection.put("/collections/#{name}", body) }
+
+        if response.success?
+          log_debug("Created collection #{name}")
+          describe_index(index: name)
+        else
+          handle_error(response)
+        end
+      end
+
+      # Delete a collection
+      #
+      # @param name [String] collection name
+      # @return [Hash] deletion result
+      def delete_index(name:)
+        response = with_error_handling { connection.delete("/collections/#{name}") }
+
+        if response.success?
+          log_debug("Deleted collection #{name}")
+          { deleted: true }
+        else
+          handle_error(response)
+        end
+      end
+
+      private
+
+      def validate_config!
+        super
+        raise ConfigurationError, "Host must be configured for Qdrant" if config.host.nil? || config.host.empty?
+      end
+
+      def connection
+        @connection ||= build_connection(
+          config.host,
+          auth_headers
+        )
+      end
+
+      # Wrap HTTP calls to handle Faraday::RetriableResponse
+      def with_error_handling
+        yield
+      rescue Faraday::RetriableResponse => e
+        handle_retriable_response(e)
+      end
+
+      def auth_headers
+        headers = {}
+        headers["api-key"] = config.api_key if config.api_key && !config.api_key.empty?
+        headers
+      end
+
+      # Generate a Qdrant point ID from string ID
+      # Qdrant supports both integer and UUID point IDs
+      # We use a hash to convert arbitrary strings to integers
+      def generate_point_id(id)
+        # If it's already a valid integer or UUID, use it
+        return id.to_i if id.to_s.match?(/^\d+$/)
+        return id if uuid?(id)
+
+        # Otherwise, store original ID in payload and use hash
+        id.to_s.hash.abs
+      end
+
+      def uuid?(str)
+        str.to_s.match?(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)
+      end
+
+      def extract_original_id(point_id)
+        point_id.to_s
+      end
+
+      # Build Qdrant filter from Vectra filter and namespace
+      def build_filter(filter, namespace)
+        conditions = []
+
+        # Add namespace filter
+        if namespace
+          conditions << {
+            key: "_namespace",
+            match: { value: namespace }
+          }
+        end
+
+        # Add metadata filters
+        if filter.is_a?(Hash)
+          filter.each do |key, value|
+            conditions << build_condition(key.to_s, value)
+          end
+        end
+
+        return nil if conditions.empty?
+
+        { must: conditions }
+      end
+
+      def build_condition(key, value)
+        case value
+        when Hash
+          # Handle operators like { "$gt" => 5 }
+          build_operator_condition(key, value)
+        when Array
+          # IN operator
+          { key: key, match: { any: value } }
+        else
+          # Exact match
+          { key: key, match: { value: value } }
+        end
+      end
+
+      def build_operator_condition(key, operator_hash)
+        operator, val = operator_hash.first
+
+        case operator.to_s
+        when "$ne"
+          { key: key, match: { except: [val] } }
+        when "$gt"
+          { key: key, range: { gt: val } }
+        when "$gte"
+          { key: key, range: { gte: val } }
+        when "$lt"
+          { key: key, range: { lt: val } }
+        when "$lte"
+          { key: key, range: { lte: val } }
+        when "$in"
+          { key: key, match: { any: val } }
+        when "$nin"
+          { key: key, match: { except: val } }
+        else # $eq or unknown operator - exact match
+          { key: key, match: { value: val } }
+        end
+      end
+
+      def transform_search_results(results)
+        results.map do |result|
+          {
+            id: extract_original_id(result["id"]),
+            score: result["score"],
+            values: result["vector"],
+            metadata: clean_payload(result["payload"])
+          }
+        end
+      end
+
+      # Remove internal fields from payload
+      def clean_payload(payload)
+        return {} unless payload
+
+        payload.reject { |k, _| k.to_s.start_with?("_") }
+      end
+
+      # Convert Vectra metric to Qdrant distance
+      def metric_to_distance(metric)
+        case metric.to_s.downcase
+        when "euclidean", "l2"
+          "Euclid"
+        when "dot_product", "dotproduct", "inner_product"
+          "Dot"
+        else # cosine or unknown - default to Cosine
+          "Cosine"
+        end
+      end
+
+      # Convert Qdrant distance to Vectra metric
+      def distance_to_metric(distance)
+        case distance.to_s
+        when "Cosine"
+          "cosine"
+        when "Euclid"
+          "euclidean"
+        when "Dot"
+          "dot_product"
+        else
+          distance.to_s.downcase
+        end
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/vectra/version.rb

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

data/lib/vectra.rb

@@ -90,11 +90,18 @@ module Vectra
 
     # Shortcut to create a Qdrant client
     #
-    # @param api_key [String] Qdrant API key
     # @param host [String] Qdrant host URL
+    # @param api_key [String, nil] Qdrant API key (optional for local instances)
     # @param options [Hash] additional options
     # @return [Client]
-    def qdrant(api_key:, host:, **options)
+    #
+    # @example Local Qdrant (no API key)
+    #   Vectra.qdrant(host: "http://localhost:6333")
+    #
+    # @example Qdrant Cloud
+    #   Vectra.qdrant(host: "https://your-cluster.qdrant.io", api_key: ENV["QDRANT_API_KEY"])
+    #
+    def qdrant(host:, api_key: nil, **options)
       Client.new(
         provider: :qdrant,
         api_key: api_key,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Mijo Kristo
@@ -55,16 +55,16 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement