vectra-client 0.2.0 → 0.2.2

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.2"
 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,

data/netlify.toml

@@ -0,0 +1,12 @@
+[build]
+  command = "cd docs && bundle install && bundle exec jekyll build"
+  publish = "docs/_site"
+
+[build.environment]
+  JEKYLL_ENV = "production"
+  RUBY_VERSION = "3.4.7"
+
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 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
@@ -207,16 +207,49 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
-- IMPLEMENTATION_GUIDE.md
 - LICENSE
-- NEW_FEATURES_v0.2.0.md
 - README.md
-- RELEASE_CHECKLIST_v0.2.0.md
 - Rakefile
 - SECURITY.md
-- USAGE_EXAMPLES.md
 - benchmarks/batch_operations_benchmark.rb
 - benchmarks/connection_pooling_benchmark.rb
+- docs/Gemfile
+- docs/_config.yml
+- docs/_layouts/default.html
+- docs/_layouts/home.html
+- docs/_layouts/page.html
+- docs/_site/api/overview/index.html
+- docs/_site/assets/main.css
+- docs/_site/assets/main.css.map
+- docs/_site/assets/minima-social-icons.svg
+- docs/_site/assets/style.css
+- docs/_site/community/contributing/index.html
+- docs/_site/examples/basic-usage/index.html
+- docs/_site/examples/index.html
+- docs/_site/feed.xml
+- docs/_site/guides/getting-started/index.html
+- docs/_site/guides/installation/index.html
+- docs/_site/index.html
+- docs/_site/providers/index.html
+- docs/_site/providers/pgvector/index.html
+- docs/_site/providers/pinecone/index.html
+- docs/_site/providers/qdrant/index.html
+- docs/_site/providers/weaviate/index.html
+- docs/_site/robots.txt
+- docs/_site/sitemap.xml
+- docs/api/overview.md
+- docs/assets/style.css
+- docs/community/contributing.md
+- docs/examples/basic-usage.md
+- docs/examples/index.md
+- docs/guides/getting-started.md
+- docs/guides/installation.md
+- docs/index.md
+- docs/providers/index.md
+- docs/providers/pgvector.md
+- docs/providers/pinecone.md
+- docs/providers/qdrant.md
+- docs/providers/weaviate.md
 - examples/active_record_demo.rb
 - examples/instrumentation_demo.rb
 - lib/generators/vectra/install_generator.rb
@@ -242,6 +275,7 @@ files:
 - lib/vectra/retry.rb
 - lib/vectra/vector.rb
 - lib/vectra/version.rb
+- netlify.toml
 homepage: https://github.com/stokry/vectra
 licenses:
 - MIT