vectra-client 0.4.0 → 1.0.1

data/lib/generators/vectra/index_generator.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Vectra
+  module Generators
+    # Rails generator for creating a vectra-enabled index for a model.
+    #
+    # @example
+    #   rails generate vectra:index Product embedding dimension:1536 provider:qdrant
+    #
+    # This will:
+    # - Generate a pgvector migration (when provider=pgvector)
+    # - Create a model concern with `has_vector`
+    # - Update the model to include the concern
+    # - Append an entry to config/vectra.yml (no secrets)
+    class IndexGenerator < Rails::Generators::Base
+      argument :model_name, type: :string, banner: "ModelName"
+      argument :column_name, type: :string, default: "embedding", banner: "column_name"
+
+      class_option :dimension, type: :numeric, default: 1536,
+                               desc: "Vector dimension (e.g. 1536 for OpenAI)"
+      class_option :provider, type: :string, default: "qdrant",
+                              desc: "Vector provider (qdrant, pgvector, pinecone, weaviate, memory)"
+      class_option :index, type: :string, default: nil,
+                           desc: "Index/collection name (defaults to table name)"
+
+      def initialize(args = [], options = {}, config = {})
+        super
+        @model_name = args[0]&.to_s
+        @column_name = (args[1] || "embedding")&.to_s
+      end
+
+      def create_migration_for_pgvector
+        return unless provider_name == "pgvector"
+
+        timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        file_name = "#{timestamp}_add_#{column_name.underscore}_to_#{table_name}.rb"
+        path = File.join("db/migrate", file_name)
+
+        migration_body = <<~RUBY
+          class Add#{column_name.camelize}To#{table_name.camelize} < ActiveRecord::Migration#{migration_version}
+            def change
+              add_column :#{table_name}, :#{column_name}, :vector, limit: #{dimension}
+            end
+          end
+        RUBY
+
+        create_file(path, migration_body)
+      end
+
+      def create_model_concern
+        path = File.join("app/models/concerns", "#{model_name.underscore}_vector.rb")
+
+        concern_body = <<~RUBY
+          # frozen_string_literal: true
+
+          module #{concern_module_name}
+            extend ActiveSupport::Concern
+
+            included do
+              include Vectra::ActiveRecord
+
+              has_vector :#{column_name},
+                         provider: :#{provider_name},
+                         index: "#{index_name}",
+                         dimension: #{dimension}
+            end
+          end
+        RUBY
+
+        create_file(path, concern_body)
+      end
+
+      def update_model_file
+        path = File.join("app/models", "#{model_name.underscore}.rb")
+
+        unless File.exist?(path)
+          create_file(
+            path,
+            <<~RUBY
+              # frozen_string_literal: true
+
+              class #{model_name.camelize} < ApplicationRecord
+                include #{concern_module_name}
+              end
+            RUBY
+          )
+          return
+        end
+
+        content = File.read(path)
+        return if content.include?("include #{concern_module_name}")
+
+        new_content = content.sub(/end\s*\z/, "  include #{concern_module_name}\nend\n")
+        File.write(path, new_content)
+      end
+
+      def update_vectra_config
+        path = File.join(destination_root || ".", "config", "vectra.yml")
+
+        existing = File.exist?(path) ? File.read(path) : ""
+        entry_key = "#{table_name}:"
+
+        return if existing.include?(entry_key)
+
+        header = +"# Vectra index configuration (do NOT store API keys here)\n"
+        header << "# Generated by vectra:index for #{model_name}\n\n"
+
+        config_body = <<~YAML
+          #{table_name}:
+            provider: #{provider_name}
+            index: #{index_name}
+            dimension: #{dimension}
+
+        YAML
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{existing.presence || header}#{config_body}")
+      end
+
+      private
+
+      def model_name
+        @model_name || raise("Model name is required")
+      end
+
+      def column_name
+        @column_name || "embedding"
+      end
+
+      def table_name
+        model_name.underscore.pluralize
+      end
+
+      def provider_name
+        options[:provider].to_s
+      end
+
+      def index_name
+        (options[:index] || table_name).to_s
+      end
+
+      def dimension
+        options[:dimension].to_i
+      end
+
+      def concern_module_name
+        "#{model_name.camelize}Vector"
+      end
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/vectra/client.rb

@@ -287,6 +287,71 @@ module Vectra
       provider.stats(index: index, namespace: namespace)
     end
 
+    # Hybrid search combining semantic (vector) and keyword (text) search
+    #
+    # Combines the best of both worlds: semantic understanding from vectors
+    # and exact keyword matching from text search.
+    #
+    # @param index [String] the index/collection name
+    # @param vector [Array<Float>] query vector for semantic search
+    # @param text [String] text query for keyword search
+    # @param alpha [Float] balance between semantic and keyword (0.0 = pure keyword, 1.0 = pure semantic)
+    # @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 results
+    # @param include_metadata [Boolean] include metadata in results
+    # @return [QueryResult] search results
+    #
+    # @example Basic hybrid search
+    #   results = client.hybrid_search(
+    #     index: 'docs',
+    #     vector: embedding,
+    #     text: 'ruby programming',
+    #     alpha: 0.7  # 70% semantic, 30% keyword
+    #   )
+    #
+    # @example Pure semantic (alpha = 1.0)
+    #   results = client.hybrid_search(
+    #     index: 'docs',
+    #     vector: embedding,
+    #     text: 'ruby',
+    #     alpha: 1.0
+    #   )
+    #
+    # @example Pure keyword (alpha = 0.0)
+    #   results = client.hybrid_search(
+    #     index: 'docs',
+    #     vector: embedding,
+    #     text: 'ruby programming',
+    #     alpha: 0.0
+    #   )
+    #
+    def hybrid_search(index:, vector:, text:, alpha: 0.5, top_k: 10, namespace: nil,
+                      filter: nil, include_values: false, include_metadata: true)
+      validate_index!(index)
+      validate_query_vector!(vector)
+      raise ValidationError, "Text query cannot be nil or empty" if text.nil? || text.empty?
+      raise ValidationError, "Alpha must be between 0.0 and 1.0" unless (0.0..1.0).include?(alpha)
+
+      unless provider.respond_to?(:hybrid_search)
+        raise UnsupportedFeatureError,
+              "Hybrid search is not supported by #{provider_name} provider"
+      end
+
+      provider.hybrid_search(
+        index: index,
+        vector: vector,
+        text: text,
+        alpha: alpha,
+        top_k: top_k,
+        namespace: namespace,
+        filter: filter,
+        include_values: include_values,
+        include_metadata: include_metadata
+      )
+    end
+
     # Get the provider name
     #
     # @return [Symbol]

data/lib/vectra/errors.rb

@@ -57,6 +57,9 @@ module Vectra
   # Raised when the provider is not supported
   class UnsupportedProviderError < Error; end
 
+  # Raised when a feature is not supported by the provider
+  class UnsupportedFeatureError < Error; end
+
   # Raised when an operation times out
   class TimeoutError < Error; end
 

data/lib/vectra/providers/pgvector.rb

@@ -94,6 +94,74 @@ module Vectra
         QueryResult.from_response(matches: matches, namespace: namespace)
       end
 
+      # Hybrid search combining vector similarity and PostgreSQL full-text search
+      #
+      # Combines pgvector similarity search with PostgreSQL's native full-text search.
+      # Requires a text search column (tsvector) in your table.
+      #
+      # @param index [String] table name
+      # @param vector [Array<Float>] query vector
+      # @param text [String] text query for full-text search
+      # @param alpha [Float] balance (0.0 = full-text, 1.0 = vector)
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @param text_column [String] column name for full-text search (default: 'content')
+      # @return [QueryResult] search results
+      #
+      # @note Your table should have a text column with a tsvector index:
+      #   CREATE INDEX idx_content_fts ON my_index USING gin(to_tsvector('english', content));
+      def hybrid_search(index:, vector:, text:, alpha:, top_k:, namespace: nil,
+                        filter: nil, include_values: false, include_metadata: true,
+                        text_column: "content")
+        ensure_table_exists!(index)
+
+        vector_literal = format_vector(vector)
+        distance_op = DISTANCE_FUNCTIONS[table_metric(index)]
+
+        # Build hybrid score: alpha * vector_similarity + (1-alpha) * text_rank
+        # Vector similarity: 1 - (distance / max_distance)
+        # Text rank: ts_rank from full-text search
+        select_cols = ["id"]
+        select_cols << "embedding" if include_values
+        select_cols << "metadata" if include_metadata
+
+        # Calculate hybrid score
+        # For vector: use cosine distance (1 - distance gives similarity)
+        # For text: use ts_rank
+        vector_score = "1.0 - (embedding #{distance_op} '#{vector_literal}'::vector)"
+        text_score = "ts_rank(to_tsvector('english', COALESCE(#{quote_ident(text_column)}, '')), " \
+                     "plainto_tsquery('english', #{escape_literal(text)}))"
+
+        # Normalize scores to 0-1 range and combine with alpha
+        hybrid_score = "(#{alpha} * #{vector_score} + (1.0 - #{alpha}) * #{text_score})"
+
+        select_cols << "#{hybrid_score} AS score"
+        select_cols << "#{vector_score} AS vector_score"
+        select_cols << "#{text_score} AS text_score"
+
+        where_clauses = build_where_clauses(namespace, filter)
+        where_clauses << "to_tsvector('english', COALESCE(#{quote_ident(text_column)}, '')) @@ " \
+                         "plainto_tsquery('english', #{escape_literal(text)})"
+
+        sql = "SELECT #{select_cols.join(', ')} FROM #{quote_ident(index)}"
+        sql += " WHERE #{where_clauses.join(' AND ')}" if where_clauses.any?
+        sql += " ORDER BY score DESC"
+        sql += " LIMIT #{top_k.to_i}"
+
+        result = execute(sql)
+        matches = result.map { |row| build_match_from_row(row, include_values, include_metadata) }
+
+        log_debug("Hybrid search returned #{matches.size} results (alpha: #{alpha})")
+
+        QueryResult.from_response(
+          matches: matches,
+          namespace: namespace
+        )
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil)
         ensure_table_exists!(index)

data/lib/vectra/providers/pinecone.rb

@@ -67,6 +67,63 @@ module Vectra
         end
       end
 
+      # Hybrid search combining dense (vector) and sparse (keyword) search
+      #
+      # Pinecone supports hybrid search using sparse-dense vectors.
+      # For text-based keyword search, you need to provide sparse vectors.
+      #
+      # @param index [String] index name
+      # @param vector [Array<Float>] dense query vector
+      # @param text [String] text query (converted to sparse vector)
+      # @param alpha [Float] balance (0.0 = sparse, 1.0 = dense)
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @return [QueryResult] search results
+      #
+      # @note For proper hybrid search, you should generate sparse vectors
+      #   from text using a tokenizer (e.g., BM25). This method accepts text
+      #   but requires sparse vector generation externally.
+      def hybrid_search(index:, vector:, alpha:, top_k:, namespace: nil,
+                        filter: nil, include_values: false, include_metadata: true, text: nil)
+        # Pinecone hybrid search requires sparse vectors
+        # For now, we'll use dense vector only and log a warning
+        # In production, users should generate sparse vectors from text
+        if text
+          log_debug("Pinecone hybrid search: text parameter ignored. " \
+                    "For true hybrid search, provide sparse vectors via sparse_values parameter.")
+        end
+
+        # Use dense vector search with alpha weighting
+        # Note: Pinecone's actual hybrid search requires sparse vectors
+        # This is a simplified implementation
+        body = {
+          vector: vector.map(&:to_f),
+          topK: top_k,
+          includeValues: include_values,
+          includeMetadata: include_metadata
+        }
+        body[:namespace] = namespace if namespace
+        body[:filter] = transform_filter(filter) if filter
+
+        # Alpha is used conceptually here - Pinecone's actual hybrid search
+        # requires sparse vectors in the query
+        response = data_connection(index).post("/query", body)
+
+        if response.success?
+          log_debug("Hybrid search returned #{response.body['matches']&.size || 0} results (alpha: #{alpha})")
+          QueryResult.from_response(
+            matches: transform_matches(response.body["matches"] || []),
+            namespace: response.body["namespace"],
+            usage: response.body["usage"]
+          )
+        else
+          handle_error(response)
+        end
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil)
         params = { ids: ids }

data/lib/vectra/providers/qdrant.rb

@@ -83,6 +83,33 @@ module Vectra
         end
       end
 
+      # Hybrid search combining vector and text search
+      #
+      # Uses Qdrant's prefetch + rescore API for efficient hybrid search
+      #
+      # @param index [String] collection name
+      # @param vector [Array<Float>] query vector
+      # @param text [String] text query for keyword search
+      # @param alpha [Float] balance (0.0 = keyword, 1.0 = vector)
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @return [QueryResult] search results
+      def hybrid_search(index:, vector:, text:, alpha:, top_k:, namespace: nil,
+                        filter: nil, include_values: false, include_metadata: true)
+        qdrant_filter = build_filter(filter, namespace)
+        body = build_hybrid_search_body(vector, text, alpha, top_k, qdrant_filter,
+                                        include_values, include_metadata)
+
+        response = with_error_handling do
+          connection.post("/collections/#{index}/points/query", body)
+        end
+
+        handle_hybrid_search_response(response, alpha, namespace)
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil) # rubocop:disable Lint/UnusedMethodArgument
         point_ids = ids.map { |id| generate_point_id(id) }
@@ -280,6 +307,38 @@ module Vectra
 
       private
 
+      def build_hybrid_search_body(vector, text, alpha, top_k, filter, include_values, include_metadata)
+        body = {
+          prefetch: {
+            query: { text: text },
+            limit: top_k * 2
+          },
+          query: { vector: vector.map(&:to_f) },
+          limit: top_k,
+          params: { alpha: alpha },
+          with_vector: include_values,
+          with_payload: include_metadata
+        }
+
+        body[:prefetch][:filter] = filter if filter
+        body[:query][:filter] = filter if filter
+        body
+      end
+
+      def handle_hybrid_search_response(response, alpha, namespace)
+        if response.success?
+          matches = transform_search_results(response.body["result"] || [])
+          log_debug("Hybrid search returned #{matches.size} results (alpha: #{alpha})")
+
+          QueryResult.from_response(
+            matches: matches,
+            namespace: namespace
+          )
+        else
+          handle_error(response)
+        end
+      end
+
       def validate_config!
         super
         raise ConfigurationError, "Host must be configured for Qdrant" if config.host.nil? || config.host.empty?

data/lib/vectra/providers/weaviate.rb

@@ -102,6 +102,43 @@ module Vectra
         end
       end
 
+      # Hybrid search combining vector and BM25 text search
+      #
+      # Uses Weaviate's hybrid search API with alpha parameter
+      #
+      # @param index [String] class name
+      # @param vector [Array<Float>] query vector
+      # @param text [String] text query for BM25 search
+      # @param alpha [Float] balance (0.0 = BM25, 1.0 = vector)
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace (not used in Weaviate)
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @return [QueryResult] search results
+      def hybrid_search(index:, vector:, text:, alpha:, top_k:, namespace: nil,
+                        filter: nil, include_values: false, include_metadata: true)
+        where_filter = build_where(filter, namespace)
+        graphql = build_hybrid_search_graphql(
+          index: index,
+          vector: vector,
+          text: text,
+          alpha: alpha,
+          top_k: top_k,
+          where_filter: where_filter,
+          include_values: include_values,
+          include_metadata: include_metadata
+        )
+        body = { "query" => graphql }
+
+        response = with_error_handling do
+          connection.post("#{API_BASE_PATH}/graphql", body)
+        end
+
+        handle_hybrid_search_response(response, index, alpha, namespace,
+                                      include_values, include_metadata)
+      end
+
       # rubocop:disable Metrics/PerceivedComplexity
       def fetch(index:, ids:, namespace: nil)
         body = {
@@ -294,6 +331,54 @@ module Vectra
 
       private
 
+      def build_hybrid_search_graphql(index:, vector:, text:, alpha:, top_k:,
+                                      where_filter:, include_values:, include_metadata:)
+        selection_block = build_selection_fields(include_values, include_metadata).join(" ")
+        build_graphql_query(index, top_k, text, alpha, vector, where_filter, selection_block)
+      end
+
+      def build_graphql_query(index, top_k, text, alpha, vector, where_filter, selection_block)
+        <<~GRAPHQL
+          {
+            Get {
+              #{index}(
+                limit: #{top_k}
+                hybrid: {
+                  query: "#{text.gsub('"', '\\"')}"
+                  alpha: #{alpha}
+                }
+                nearVector: { vector: [#{vector.map { |v| format('%.10f', v.to_f) }.join(', ')}] }
+                #{"where: #{JSON.generate(where_filter)}" if where_filter}
+              ) {
+                #{selection_block}
+              }
+            }
+          }
+        GRAPHQL
+      end
+
+      def build_selection_fields(include_values, include_metadata)
+        fields = ["_additional { id distance }"]
+        fields << "vector" if include_values
+        fields << "metadata" if include_metadata
+        fields
+      end
+
+      def handle_hybrid_search_response(response, index, alpha, namespace,
+                                        include_values, include_metadata)
+        if response.success?
+          matches = extract_query_matches(response.body, index, include_values, include_metadata)
+          log_debug("Hybrid search returned #{matches.size} results (alpha: #{alpha})")
+
+          QueryResult.from_response(
+            matches: matches,
+            namespace: namespace
+          )
+        else
+          handle_error(response)
+        end
+      end
+
       def validate_config!
         super
         raise ConfigurationError, "Host must be configured for Weaviate" if config.host.nil? || config.host.empty?

data/lib/vectra/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Mijo Kristo
@@ -252,6 +252,11 @@ files:
 - docs/_site/robots.txt
 - docs/_site/sitemap.xml
 - docs/api/overview.md
+- docs/assets/favicon.svg
+- docs/assets/logo.svg
+- docs/assets/radme.png
+- docs/assets/readme-new.png
+- docs/assets/seo.png
 - docs/assets/style.css
 - docs/community/contributing.md
 - docs/examples/basic-usage.md
@@ -282,6 +287,7 @@ files:
 - examples/grafana-setup.md
 - examples/instrumentation_demo.rb
 - examples/prometheus-exporter.rb
+- lib/generators/vectra/index_generator.rb
 - lib/generators/vectra/install_generator.rb
 - lib/generators/vectra/templates/enable_pgvector_extension.rb
 - lib/generators/vectra/templates/vectra.rb