search-engine-for-typesense 1.0.0

data/lib/search_engine/observability.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Lightweight utilities for observability concerns (redaction, excerpts).
+  #
+  # Provides a single public entry point {.redact} used by the client and
+  # optional subscribers to produce compact, redacted payloads that avoid
+  # leaking secrets while keeping useful context.
+  module Observability
+    # Keys that are considered sensitive and must be redacted whenever present.
+    SENSITIVE_KEY_PATTERN = /key|token|secret|password/i
+
+    # Whitelisted search parameter keys to include in payload excerpts.
+    PARAM_WHITELIST = %i[
+      q query_by include_fields exclude_fields per_page page infix filter_by group_by group_limit group_missing_values
+      facet_by max_facet_values facet_query
+      num_typos drop_tokens_threshold prioritize_exact_match query_by_weights
+    ].freeze
+
+    # Maximum length for `q` values before truncation.
+    MAX_Q_LENGTH = 128
+
+    # Redact a value producing a new structure without mutating the input.
+    #
+    # - When given a Hash of search params, returns a compact excerpt that only
+    #   includes whitelisted keys with secrets redacted and `filter_by` masked.
+    # - When given an Array, returns a redacted array by applying the same logic
+    #   to each element.
+    # - For other values, returns a best-effort redacted representation.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def self.redact(value)
+      case value
+      when Hash
+        redact_params_hash(value)
+      when Array
+        value.map { |v| redact(v) }
+      when String
+        redact_string(value)
+      else
+        value
+      end
+    end
+
+    # Internal: Redact a Hash presumed to be Typesense search params.
+    # Returns a new Hash with only whitelisted keys preserved. Sensitive keys
+    # are not included; `filter_by` literals are masked.
+    def self.redact_params_hash(params)
+      result = {}
+
+      PARAM_WHITELIST.each do |key|
+        next unless params.key?(key)
+
+        val = params[key]
+        case key
+        when :q
+          result[:q] = truncate_q(val)
+        when :filter_by
+          result[:filter_by] = redact_filter_by(val)
+        else
+          result[key] = redact_simple_value(val)
+        end
+      end
+
+      result
+    end
+
+    # Internal: Best-effort redaction for simple scalar values.
+    def self.redact_simple_value(value)
+      return value unless value.is_a?(String)
+
+      redact_string(value)
+    end
+
+    # Internal: Truncate overly long query strings.
+    def self.truncate_q(query)
+      return query unless query.is_a?(String)
+
+      query.length > MAX_Q_LENGTH ? "#{query[0, MAX_Q_LENGTH]}..." : query
+    end
+
+    # Internal: Redact secrets in a string and mask obvious literal fragments.
+    def self.redact_string(str)
+      return str unless str.is_a?(String)
+
+      # Mask obvious quoted literals first
+      redacted = str.gsub(/"[^"]*"|'[^']*'/, '***')
+
+      # Mask numeric literals (best-effort)
+      redacted.gsub(/\b\d+(?:\.\d+)?\b/, '***')
+    end
+
+    # Internal: Mask literal values in Typesense filter expressions while
+    # preserving attribute/operator structure. Best-effort and lightweight.
+    # Examples:
+    #   "category_id:=123" => "category_id:=***"
+    #   "price:>10 && brand:='Acme'" => "price:>*** && brand:=***"
+    def self.redact_filter_by(filter)
+      return filter unless filter.is_a?(String)
+
+      # Replace values that follow a comparator or a colon with *** until a
+      # delimiter is reached. Also mask quoted strings and numbers.
+      masked = filter.gsub(/([!:><=]{1,2})\s*([^\s)&|]+)/, '\1***')
+      masked = masked.gsub(/"[^"]*"|'[^']*'/, '***')
+      masked.gsub(/\b\d+(?:\.\d+)?\b/, '***')
+    end
+
+    # Build a filtered URL/common options hash for payloads.
+    # @param url_opts [Hash]
+    # @return [Hash]
+    def self.filtered_url_opts(url_opts)
+      return {} unless url_opts.is_a?(Hash)
+
+      {
+        use_cache: url_opts[:use_cache],
+        cache_ttl: url_opts[:cache_ttl]
+      }
+    end
+
+    # Compute a SHA1 hex digest for a value.
+    # @param value [#to_s]
+    # @return [String]
+    def self.sha_1(value)
+      require 'digest'
+      Digest::SHA1.hexdigest(value.to_s)
+    end
+
+    # Return a shortened hash prefix for display/logging.
+    # @param hexdigest [String]
+    # @param length [Integer]
+    # @return [String]
+    def self.short_hash(hexdigest, length = 8)
+      s = hexdigest.to_s
+      s[0, length]
+    end
+
+    # Truncate and normalize a free-text message to a single line.
+    # @param message [String]
+    # @param max [Integer]
+    # @return [String]
+    def self.truncate_message(message, max = 200)
+      s = message.to_s.gsub(/\s+/, ' ').strip
+      s[0, max]
+    end
+
+    # Compute partition helpers used in logs: prefer raw numeric; hash strings.
+    # @param partition [Object]
+    # @return [Hash] { partition: <raw>, partition_hash: <String,nil> }
+    def self.partition_fields(partition)
+      if partition.is_a?(Numeric)
+        { partition: partition, partition_hash: nil }
+      else
+        hex = sha_1(partition)
+        { partition: partition, partition_hash: short_hash(hex) }
+      end
+    end
+
+    private_class_method :redact_params_hash, :redact_simple_value, :truncate_q,
+                         :redact_string, :redact_filter_by
+  end
+end

data/lib/search_engine/operations.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Operations namespace for convenience access to operational endpoints.
+  #
+  # Provides small wrappers around {SearchEngine::Client} for metrics, stats,
+  # and health, emitting instrumentation and supporting dependency injection
+  # via an optional client.
+  module Operations
+    class << self
+      # Retrieve raw server metrics.
+      #
+      # @param client [SearchEngine::Client, nil] optional injected client
+      # @return [Hash] raw payload from Typesense `/metrics.json`
+      # @see SearchEngine::Client#metrics
+      def metrics(client: nil)
+        SearchEngine::Instrumentation.instrument('search_engine.operations.metrics', {}) do
+          ts_client = client || SearchEngine.client
+          ts_client.metrics
+        end
+      end
+
+      # Retrieve raw server stats.
+      #
+      # @param client [SearchEngine::Client, nil] optional injected client
+      # @return [Hash] raw payload from Typesense `/stats.json`
+      # @see SearchEngine::Client#stats
+      def stats(client: nil)
+        SearchEngine::Instrumentation.instrument('search_engine.operations.stats', {}) do
+          ts_client = client || SearchEngine.client
+          ts_client.stats
+        end
+      end
+
+      # Retrieve server health.
+      #
+      # @param client [SearchEngine::Client, nil] optional injected client
+      # @return [Hash] Typesense health response
+      # @see SearchEngine::Client#health
+      def health(client: nil)
+        SearchEngine::Instrumentation.instrument('search_engine.operations.health', {}) do
+          ts_client = client || SearchEngine.client
+          ts_client.health
+        end
+      end
+
+      private
+
+      def configured_client
+        return unless SearchEngine.config.respond_to?(:client)
+
+        SearchEngine.config.client
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/search_engine/otel.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Optional OpenTelemetry adapter that translates unified instrumentation
+  # events into OpenTelemetry spans. Activation is gated by the presence of the
+  # OpenTelemetry SDK and by `SearchEngine.config.opentelemetry.enabled`.
+  #
+  # @since M8
+  # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+  #
+  # Public API:
+  # - .installed? => Boolean
+  # - .enabled?   => Boolean (config + SDK present)
+  # - .start!     => idempotently subscribes to events
+  # - .stop!      => unsubscribes
+  module Otel
+    class << self
+      # @return [Boolean] whether the OpenTelemetry SDK is available
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+      def installed?
+        defined?(::OpenTelemetry::SDK)
+      end
+
+      # @return [Boolean] whether the adapter should be active
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+      def enabled?
+        installed? && SearchEngine.respond_to?(:config) && SearchEngine.config&.opentelemetry&.enabled
+      end
+
+      # Start the adapter (idempotent). No-ops when disabled or SDK unavailable.
+      # @return [Object, nil] subscription handle or nil when not installed/enabled
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+      def start!
+        stop!
+        return nil unless enabled?
+        return nil unless defined?(ActiveSupport::Notifications)
+
+        @service_name = begin
+          SearchEngine.config.opentelemetry.service_name
+        rescue StandardError
+          'search_engine'
+        end
+        @tracer = tracer_provider&.tracer('search_engine', SearchEngine::VERSION)
+
+        @handle = ActiveSupport::Notifications.subscribe(/^search_engine\./) do |*args|
+          # Lazily build Event only when sampled downstream; allocation kept minimal otherwise
+          event = ActiveSupport::Notifications::Event.new(*args)
+          handle_event(event)
+        end
+      rescue StandardError
+        # Never raise from adapter startup
+        nil
+      end
+
+      # Stop the adapter if previously started.
+      # @return [Boolean]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/observability#opentelemetry
+      def stop!
+        return false unless defined?(ActiveSupport::Notifications)
+        return false unless @handle
+
+        ActiveSupport::Notifications.unsubscribe(@handle)
+        @handle = nil
+        true
+      end
+
+      private
+
+      def tracer_provider
+        return nil unless installed?
+
+        ::OpenTelemetry.tracer_provider
+      rescue StandardError
+        nil
+      end
+
+      attr_reader :tracer
+
+      def handle_event(event)
+        return unless tracer
+
+        payload = event.payload || {}
+        duration = compute_duration(event, payload)
+
+        tracer.in_span(event.name) do |span|
+          apply_common_attributes(span, event, payload, duration)
+          apply_url_attributes(span, payload)
+          apply_feature_attributes(span, payload)
+          apply_indexer_schema_attributes(span, payload)
+          apply_params_preview(span, payload)
+          apply_status(span, payload)
+        end
+      rescue StandardError
+        # Never raise from subscriber
+        nil
+      end
+
+      def compute_duration(event, payload)
+        d = (event.respond_to?(:duration) ? event.duration : payload[:duration_ms]).to_f
+        d = payload[:duration_ms].to_f if d.zero? && payload[:duration_ms]
+        d.round(1)
+      end
+
+      def apply_common_attributes(span, event, payload, duration)
+        assign_attr(span, 'service.name', @service_name)
+        assign_attr(span, 'se.event', event.name)
+        assign_attr(span, 'se.cid', payload[:correlation_id]) if payload.key?(:correlation_id)
+        assign_attr(span, 'http.status_code', payload[:http_status]) if payload.key?(:http_status)
+        assign_attr(span, 'se.duration_ms', duration) if duration.positive?
+        return unless payload[:collection] || payload[:logical]
+
+        assign_attr(span, 'se.collection', payload[:collection] || payload[:logical])
+      end
+
+      def apply_url_attributes(span, payload)
+        url_opts = payload[:url_opts]
+        return unless url_opts.is_a?(Hash)
+
+        assign_attr(span, 'se.url_use_cache', url_opts[:use_cache]) if url_opts.key?(:use_cache)
+        assign_attr(span, 'se.url_cache_ttl', url_opts[:cache_ttl]) if url_opts.key?(:cache_ttl)
+      end
+
+      def apply_feature_attributes(span, p)
+        assign_attr(span, 'se.labels_count', Array(p[:labels]).size) if p.key?(:labels)
+        assign_attr(span, 'se.searches_count', p[:searches_count]) if p.key?(:searches_count)
+        assign_attr(span, 'se.node_count', p[:node_count]) if p.key?(:node_count)
+        assign_attr(span, 'se.join_count', p[:join_count]) if p.key?(:join_count)
+        assign_attr(span, 'se.groups_count', p[:groups_count]) if p.key?(:groups_count)
+        assign_attr(span, 'se.group_by', p[:field] || p[:group_by]) if p.key?(:field) || p.key?(:group_by)
+        assign_attr(span, 'se.group_limit', p[:limit] || p[:group_limit]) if p.key?(:limit) || p.key?(:group_limit)
+        return unless p.key?(:missing_values) || p.key?(:group_missing_values)
+
+        assign_attr(span, 'se.group_missing_values', p[:missing_values] || p[:group_missing_values])
+      end
+
+      def apply_indexer_schema_attributes(span, p)
+        %i[into partition partition_hash batch_index docs_count success_count failure_count attempts bytes_sent
+           deleted_count searches_count fields_changed_count added_count removed_count in_sync].each do |k|
+          assign_attr(span, "se.#{k}", p[k]) if p.key?(k)
+        end
+        # New event attributes (redacted/summarized)
+        %i[fields_count queries_count max_facet_values sort_flags conflicts].each do |k|
+          assign_attr(span, "se.#{k}", p[k]) if p.key?(k)
+        end
+        %i[full_fields_count affix_tokens snippet_threshold tag_kind].each do |k|
+          assign_attr(span, "se.#{k}", p[k]) if p.key?(k)
+        end
+        %i[use_synonyms use_stopwords source].each do |k|
+          assign_attr(span, "se.#{k}", p[k]) if p.key?(k)
+        end
+        if p.key?(:shapes)
+          shapes = p[:shapes] || {}
+          assign_attr(span, 'se.shapes.point', shapes[:point]) if shapes.key?(:point)
+          assign_attr(span, 'se.shapes.rect', shapes[:rect]) if shapes.key?(:rect)
+          assign_attr(span, 'se.shapes.circle', shapes[:circle]) if shapes.key?(:circle)
+        end
+        %i[sort_mode radius_bucket].each do |k|
+          assign_attr(span, "se.#{k}", p[k]) if p.key?(k)
+        end
+        %i[query_vector_present dims hybrid_weight ann_params_present].each do |k|
+          assign_attr(span, "se.#{k}", p[k]) if p.key?(k)
+        end
+        %i[early_limit validate_max applied_strategy triggered total_hits].each do |k|
+          assign_attr(span, "se.#{k}", p[k]) if p.key?(k)
+        end
+      end
+
+      def apply_params_preview(span, payload)
+        return unless payload.key?(:params_preview)
+
+        red = SearchEngine::Instrumentation.redact(payload[:params_preview])
+        keys_count = (red.is_a?(Hash) ? red.keys.size : nil)
+        assign_attr(span, 'se.params_preview_keys', keys_count) if keys_count
+      rescue StandardError
+        nil
+      end
+
+      def apply_status(span, payload)
+        http = payload[:http_status]
+        status = payload[:status]
+        err_class = payload[:error_class]
+        err_msg = payload[:error_message]
+
+        if (status && status.to_sym == :error) || (http && http.to_i >= 400) || err_class
+          # Record a lightweight exception event with sanitized message
+          if err_class || err_msg
+            msg = SearchEngine::Observability.truncate_message(err_msg || err_class.to_s, 200)
+            span.add_event(
+              'exception',
+              attributes: {
+                'exception.type' => (err_class || 'Error').to_s,
+                'exception.message' => msg
+              }
+            )
+          end
+          span_status_error(span, err_msg || err_class)
+        else
+          span_status_ok(span)
+        end
+      end
+
+      def span_status_error(span, description = nil)
+        span.status = ::OpenTelemetry::Trace::Status.error(description.to_s) if defined?(::OpenTelemetry::Trace::Status)
+      rescue StandardError
+        nil
+      end
+
+      def span_status_ok(span)
+        span.status = ::OpenTelemetry::Trace::Status.ok if defined?(::OpenTelemetry::Trace::Status)
+      rescue StandardError
+        nil
+      end
+
+      def assign_attr(span, key, value)
+        return if value.nil?
+
+        span.set_attribute(key, value)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/search_engine/partitioner.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Compiles and validates partitioning directives captured by the index DSL.
+  #
+  # Provides an immutable object with callables for:
+  # - partitions -> Enumerable of partition keys
+  # - partition_fetch(partition) -> Enumerable of batches (Arrays of records)
+  # - before_hook(partition)
+  # - after_hook(partition)
+  class Partitioner
+    # Immutable compiled holder
+    class Compiled
+      attr_reader :klass, :partitions_proc, :partition_fetch_proc, :before_hook_proc, :after_hook_proc, :max_parallel
+
+      def initialize(klass:, partitions_proc:, partition_fetch_proc:, before_hook_proc:, after_hook_proc:,
+                     max_parallel: 1)
+        @klass = klass
+        @partitions_proc = partitions_proc
+        @partition_fetch_proc = partition_fetch_proc
+        validate_hook_arity!(before_hook_proc, name: 'before_partition') if before_hook_proc
+        validate_hook_arity!(after_hook_proc, name: 'after_partition') if after_hook_proc
+        @before_hook_proc = before_hook_proc
+        @after_hook_proc = after_hook_proc
+        mp = begin
+          Integer(max_parallel)
+        rescue StandardError
+          1
+        end
+        @max_parallel = mp.positive? ? mp : 1
+        freeze
+      end
+
+      # Enumerate partition keys. Validates the return value shape.
+      # @return [Enumerable] list/Enumerable of opaque partition tokens
+      # @raise [SearchEngine::Errors::InvalidParams] when the block does not return an Enumerable
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      def partitions
+        return [] unless @partitions_proc
+
+        res = @partitions_proc.call
+        unless res.respond_to?(:each)
+          raise SearchEngine::Errors::InvalidParams,
+                'partitions block must return an Enumerable of partition keys (Array acceptable). ' \
+                'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning.'
+        end
+        res
+      end
+
+      # Return an Enumerator for batches for the given partition, validating element shape.
+      # @param partition [Object]
+      # @return [Enumerable<Array>] enumerator yielding Arrays of records
+      # @raise [ArgumentError] when partition_fetch is not defined
+      # @raise [SearchEngine::Errors::InvalidParams] when the block returns a non-enumerable or yields non-arrays
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      def partition_fetch_enum(partition)
+        raise ArgumentError, 'partition_fetch not defined' unless @partition_fetch_proc
+
+        enum = @partition_fetch_proc.call(partition)
+        unless enum.respond_to?(:each)
+          raise SearchEngine::Errors::InvalidParams,
+                'partition_fetch must return an Enumerable yielding Arrays of records. ' \
+                'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning.'
+        end
+
+        Enumerator.new do |y|
+          idx = 0
+          enum.each do |batch|
+            unless batch.is_a?(Array) || batch.respond_to?(:to_a)
+              raise SearchEngine::Errors::InvalidParams,
+                    "partition_fetch must yield Arrays of records; got #{batch.class} at index #{idx}."
+            end
+            y << (batch.is_a?(Array) ? batch : batch.to_a)
+            idx += 1
+          end
+        end
+      end
+
+      private
+
+      def validate_hook_arity!(proc_obj, name:)
+        ar = proc_obj.arity
+        return if ar == 1 || ar.negative?
+
+        raise SearchEngine::Errors::InvalidParams, "#{name} block must accept exactly 1 parameter (partition)."
+      end
+    end
+
+    class << self
+      # Resolve a compiled partitioner for a model class, or nil if directives are absent.
+      # @param klass [Class]
+      # @return [SearchEngine::Partitioner::Compiled, nil]
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#partitioning
+      def for(klass)
+        dsl = mapper_dsl_for(klass)
+        return nil unless dsl
+
+        any = dsl[:partitions] || dsl[:partition_fetch] || dsl[:before_partition] || dsl[:after_partition]
+        return nil unless any
+
+        cache[klass] ||= compile(klass, dsl)
+      end
+
+      private
+
+      def cache
+        @cache ||= {}
+      end
+
+      def compile(klass, dsl)
+        Compiled.new(
+          klass: klass,
+          partitions_proc: dsl[:partitions],
+          partition_fetch_proc: dsl[:partition_fetch],
+          before_hook_proc: dsl[:before_partition],
+          after_hook_proc: dsl[:after_partition],
+          max_parallel: dsl[:partition_max_parallel]
+        )
+      end
+
+      def mapper_dsl_for(klass)
+        return unless klass.instance_variable_defined?(:@__mapper_dsl__)
+
+        klass.instance_variable_get(:@__mapper_dsl__)
+      end
+    end
+  end
+end

data/lib/search_engine/ranking_plan.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Pure, deterministic normalizer for ranking/typo/prefix tuning.
+  # Accepts relation context, effective query_by, and raw ranking state,
+  # validates and emits authoritative Typesense params.
+  #
+  # Usage: RankingPlan.new(relation: rel, query_by: "name,description", ranking: {...}).params
+  class RankingPlan
+    # @return [Hash]
+    attr_reader :params
+
+    # @param relation [SearchEngine::Relation]
+    # @param query_by [String, nil]
+    # @param ranking [Hash]
+    def initialize(relation:, query_by:, ranking: {})
+      @relation = relation
+      @raw_query_by = query_by
+      @raw = ranking || {}
+      @params = compile!
+      freeze
+    end
+
+    # Return effective query_by fields as an Array<String> (trimmed, non-blank)
+    def effective_query_by_fields
+      resolve_query_by(@raw_query_by)
+    end
+
+    private
+
+    def compile!
+      out = {}
+
+      out[:num_typos] = @raw[:num_typos] if @raw.key?(:num_typos) && !@raw[:num_typos].nil?
+
+      if @raw.key?(:drop_tokens_threshold) && !@raw[:drop_tokens_threshold].nil?
+        out[:drop_tokens_threshold] = @raw[:drop_tokens_threshold]
+      end
+
+      if @raw.key?(:prioritize_exact_match) && !@raw[:prioritize_exact_match].nil?
+        out[:prioritize_exact_match] = @raw[:prioritize_exact_match]
+      end
+
+      if (weights = @raw[:query_by_weights])
+        fields = effective_query_by_fields
+        if fields.empty?
+          raise SearchEngine::Errors::InvalidOption.new(
+            'InvalidOption: query_by is empty; cannot apply query_by_weights',
+            hint: 'Set SearchEngine.config.default_query_by or pass options(query_by: ...)',
+            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/ranking#weights'
+          )
+        end
+
+        normalized_weights = build_weight_vector!(fields, weights)
+        if normalized_weights.all? { |w| w.to_i.zero? }
+          raise SearchEngine::Errors::InvalidOption.new(
+            'InvalidOption: at least one weighted field must have weight > 0',
+            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/ranking#weights'
+          )
+        end
+        out[:query_by_weights] = normalized_weights.join(',')
+      end
+
+      out
+    end
+
+    def resolve_query_by(query_by)
+      query_by.to_s.split(',').map(&:strip).reject(&:empty?)
+    end
+
+    def build_weight_vector!(fields, weight_map)
+      # Validate that provided keys are subset of effective query_by
+      known = fields
+      provided = weight_map.keys.map(&:to_s)
+      unknown = provided - known
+      unless unknown.empty?
+        suggestions = suggest_for(unknown.first, known)
+        suffix = if suggestions.empty?
+                   ''
+                 elsif suggestions.length == 1
+                   " (did you mean #{suggestions.first.inspect}?)"
+                 else
+                   others = suggestions[0..-2].map(&:inspect).join(', ')
+                   last = suggestions.last.inspect
+                   " (did you mean #{others}, or #{last}?)"
+                 end
+        raise SearchEngine::Errors::InvalidOption.new(
+          "InvalidOption: weight specified for unknown field #{unknown.first.inspect}#{suffix}",
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/relation-reference#selection',
+          details: { unknown: unknown.first, allowed: known }
+        )
+      end
+
+      fields.map { |f| Integer(weight_map.fetch(f, 1)) }
+    rescue ArgumentError, TypeError
+      raise SearchEngine::Errors::InvalidOption.new(
+        'InvalidOption: query_by_weights must compile to integers',
+        doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/ranking#weights'
+      )
+    end
+
+    def suggest_for(input, candidates)
+      return [] if candidates.empty?
+
+      begin
+        require 'did_you_mean'
+        require 'did_you_mean/levenshtein'
+      rescue StandardError
+        return []
+      end
+
+      distances = candidates.each_with_object({}) do |cand, acc|
+        acc[cand] = DidYouMean::Levenshtein.distance(input.to_s, cand.to_s)
+      end
+      distances.sort_by { |(_c, d)| d }.take(3).select { |(_c, d)| d <= 2 }.map(&:first)
+    end
+  end
+end