noiseless 0.0.0 → 0.1.0

data/lib/noiseless/pagination.rb

@@ -0,0 +1,375 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module Pagination
+    DEFAULT_PER_PAGE = 20
+    MAX_PER_PAGE = 100
+
+    # Simple paginated array wrapper - no external dependencies
+    class PaginatedArray < Array
+      attr_accessor :current_page, :per_page, :total_count
+
+      def initialize(records, current_page:, per_page:, total_count:)
+        super(records)
+        @current_page = current_page
+        @per_page = per_page
+        @total_count = total_count
+      end
+
+      def total_pages
+        return 1 if total_count.zero? || per_page.zero?
+
+        (total_count.to_f / per_page).ceil
+      end
+
+      def next_page
+        current_page < total_pages ? current_page + 1 : nil
+      end
+
+      def prev_page
+        current_page > 1 ? current_page - 1 : nil
+      end
+
+      def first_page?
+        current_page == 1
+      end
+
+      def last_page?
+        current_page >= total_pages
+      end
+
+      def out_of_range?
+        current_page > total_pages
+      end
+
+      def offset_value
+        (current_page - 1) * per_page
+      end
+
+      def limit_value
+        per_page
+      end
+
+      # JSON serialization for API responses
+      def pagination_metadata
+        {
+          current_page: current_page,
+          per_page: per_page,
+          total_count: total_count,
+          total_pages: total_pages,
+          next_page: next_page,
+          prev_page: prev_page
+        }
+      end
+    end
+
+    # Keyset pagination cursor
+    class Cursor
+      attr_reader :field, :value, :direction
+
+      def initialize(field:, value:, direction: :asc)
+        @field = field.to_s
+        @value = value
+        @direction = direction.to_sym
+      end
+
+      # Encode cursor for API response
+      def encode
+        Base64.urlsafe_encode64(JSON.generate({ f: field, v: value, d: direction }))
+      end
+
+      # Decode cursor from API request
+      def self.decode(encoded)
+        return nil if encoded.blank?
+
+        data = JSON.parse(Base64.urlsafe_decode64(encoded))
+        new(field: data["f"], value: data["v"], direction: data["d"]&.to_sym || :asc)
+      rescue StandardError
+        nil
+      end
+
+      # Build next cursor from last record
+      def self.from_record(record, field:, direction: :asc)
+        value = record.respond_to?(field) ? record.send(field) : record[field.to_s]
+        new(field: field, value: value, direction: direction)
+      end
+    end
+
+    # Keyset paginated result
+    class KeysetResult
+      attr_reader :records, :next_cursor, :has_more
+
+      def initialize(records, next_cursor: nil, has_more: false)
+        @records = records
+        @next_cursor = next_cursor
+        @has_more = has_more
+      end
+
+      def each(&)
+        records.each(&)
+      end
+
+      include Enumerable
+
+      def to_a
+        records
+      end
+
+      delegate :size, to: :records
+
+      delegate :empty?, to: :records
+
+      # JSON serialization for API responses
+      def pagination_metadata
+        {
+          has_more: has_more,
+          next_cursor: next_cursor&.encode
+        }
+      end
+    end
+
+    # Search paginator - builds and executes paginated queries
+    class SearchPaginator
+      include Enumerable
+
+      def initialize(model_class, page: 1, per_page: nil)
+        @model_class = model_class
+        @current_page = [page.to_i, 1].max
+        @per_page = [(per_page || DEFAULT_PER_PAGE).to_i, MAX_PER_PAGE].min
+        @query_builder = QueryBuilder.new(model_class)
+        @executed = false
+        @results = nil
+      end
+
+      def page(num)
+        SearchPaginator.new(@model_class, page: num, per_page: @per_page)
+      end
+
+      def per(num)
+        SearchPaginator.new(@model_class, page: @current_page, per_page: num)
+      end
+
+      # Pagination info
+      attr_reader :current_page
+
+      def limit_value
+        @per_page
+      end
+
+      def total_count
+        execute_search unless @executed
+        @total_count || 0
+      end
+
+      def total_pages
+        return 1 if total_count.zero?
+
+        (total_count.to_f / @per_page).ceil
+      end
+
+      def next_page
+        current_page < total_pages ? current_page + 1 : nil
+      end
+
+      def prev_page
+        current_page > 1 ? current_page - 1 : nil
+      end
+
+      def first_page?
+        current_page == 1
+      end
+
+      def last_page?
+        current_page >= total_pages
+      end
+
+      def out_of_range?
+        current_page > total_pages
+      end
+
+      def offset_value
+        (@current_page - 1) * @per_page
+      end
+
+      delegate :size, to: :to_a
+
+      def length
+        size
+      end
+
+      def empty?
+        size.zero?
+      end
+
+      # Enumerable interface
+      def each(&)
+        return enum_for(__method__) unless block_given?
+
+        to_a.each(&)
+      end
+
+      def to_a
+        execute_search unless @executed
+        @results.to_a
+      end
+
+      # Query building delegation
+      def match(field, value, **)
+        @query_builder.match(field, value, **)
+        self
+      end
+
+      def multi_match(query, fields, **)
+        @query_builder.multi_match(query, fields, **)
+        self
+      end
+
+      def filter(field, value, **)
+        @query_builder.filter(field, value, **)
+        self
+      end
+
+      def sort(field, direction = :asc, **)
+        @query_builder.sort(field, direction, **)
+        self
+      end
+
+      def aggregation(name, type, **)
+        @query_builder.aggregation(name, type, **)
+        self
+      end
+
+      def geo_distance(field, lat:, lon:, distance:, **)
+        @query_builder.geo_distance(field, lat: lat, lon: lon, distance: distance, **)
+        self
+      end
+
+      def vector(field, embedding, **)
+        @query_builder.vector(field, embedding, **)
+        self
+      end
+
+      # Response access
+      def results
+        execute_search unless @executed
+        @results
+      end
+
+      def aggregations
+        execute_search unless @executed
+        @results&.aggregations
+      end
+
+      def suggestions
+        execute_search unless @executed
+        @results&.suggestions
+      end
+
+      def hits
+        execute_search unless @executed
+        @results&.hits || []
+      end
+
+      def took
+        execute_search unless @executed
+        @results&.took
+      end
+
+      # Records-specific methods
+      def each_with_hit(&)
+        return enum_for(__method__) unless block_given?
+
+        execute_search unless @executed
+        if @results.respond_to?(:each_with_hit)
+          @results.each_with_hit(&)
+        else
+          to_a.each_with_index { |record, index| yield(record, hits[index]) }
+        end
+      end
+
+      def map_with_hit(&)
+        return enum_for(__method__) unless block_given?
+
+        each_with_hit.map(&)
+      end
+
+      # JSON metadata for API responses
+      def pagination_metadata
+        {
+          current_page: current_page,
+          per_page: @per_page,
+          total_count: total_count,
+          total_pages: total_pages,
+          next_page: next_page,
+          prev_page: prev_page
+        }
+      end
+
+      private
+
+      def execute_search
+        @query_builder.paginate(page: @current_page, per_page: @per_page)
+
+        client = Noiseless.connections.client(@model_class.connection)
+        ast = @query_builder.to_ast
+        @results = client.search(ast, model_class: @model_class)
+        @total_count = @results.total
+        @executed = true
+      end
+    end
+
+    # Extend response classes with pagination support
+    module ResponsePagination
+      def total_pages
+        return 1 if total.zero? || @per_page.nil?
+
+        (total.to_f / @per_page).ceil
+      end
+
+      def current_page
+        return 1 unless @from && @per_page
+
+        (@from / @per_page) + 1
+      end
+
+      def next_page
+        current_page < total_pages ? current_page + 1 : nil
+      end
+
+      def prev_page
+        current_page > 1 ? current_page - 1 : nil
+      end
+
+      def first_page?
+        current_page == 1
+      end
+
+      def last_page?
+        current_page >= total_pages
+      end
+
+      def out_of_range?
+        current_page > total_pages
+      end
+
+      def limit_value
+        @per_page
+      end
+
+      def offset_value
+        @from || 0
+      end
+
+      def pagination_metadata
+        {
+          current_page: current_page,
+          per_page: @per_page,
+          total_count: total,
+          total_pages: total_pages,
+          next_page: next_page,
+          prev_page: prev_page
+        }
+      end
+    end
+  end
+end

data/lib/noiseless/query_builder.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+module Noiseless
+  class QueryBuilder
+    def initialize(model)
+      @model        = model
+      @indexes      = determine_indexes(model)
+      @nodes        = []
+      @aggregations = []
+      @collapse     = nil
+      @search_after = nil
+      @hybrid       = nil
+      @pipeline     = nil
+      @image_query  = nil
+      @conversation = nil
+      @joins        = []
+      @remove_duplicates = nil
+      @facet_sample_slope = nil
+      @pinned_hits = nil
+    end
+
+    def indexes(names)
+      @indexes = Array(names).map(&:to_s)
+      self
+    end
+
+    def match(field, value)
+      @nodes << AST::Match.new(field, value)
+      self
+    end
+
+    def multi_match(query, fields, **)
+      @nodes << AST::MultiMatch.new(query, fields, **)
+      self
+    end
+
+    def wildcard(field, value)
+      @nodes << AST::Wildcard.new(field, value)
+      self
+    end
+
+    def range(field, gte: nil, lte: nil, gt: nil, lt: nil)
+      @nodes << AST::Range.new(field, gte: gte, lte: lte, gt: gt, lt: lt)
+      self
+    end
+
+    def prefix(field, value)
+      @nodes << AST::Prefix.new(field, value)
+      self
+    end
+
+    def filter(field, value)
+      @nodes << AST::Filter.new(field, value)
+      self
+    end
+
+    alias where filter
+
+    def sort(field, dir = :asc)
+      @nodes << AST::Sort.new(field, dir)
+      self
+    end
+
+    alias order sort
+
+    def paginate(page: 1, per_page: 20)
+      @nodes << AST::Paginate.new(page, per_page)
+      self
+    end
+
+    def limit(size)
+      @nodes << AST::Paginate.new(1, size)
+      self
+    end
+
+    def offset(from)
+      # Calculate page based on offset and current per_page
+      existing_paginate = @nodes.find { |n| n.is_a?(AST::Paginate) }
+      per_page = existing_paginate&.per_page || 20
+      page = (from / per_page) + 1
+      @nodes.reject! { |n| n.is_a?(AST::Paginate) }
+      @nodes << AST::Paginate.new(page, per_page)
+      self
+    end
+
+    def aggregation(name, type, field: nil, **, &)
+      sub_aggs = []
+      if block_given?
+        sub_builder = AST::AggregationBuilder.new
+        sub_builder.instance_eval(&)
+        sub_aggs = sub_builder.aggregations
+      end
+
+      @aggregations << AST::Aggregation.new(name, type, field: field, sub_aggregations: sub_aggs, **)
+      self
+    end
+
+    alias agg aggregation
+
+    def collapse(field, inner_hits: nil, max_concurrent_group_searches: nil)
+      @collapse = AST::Collapse.new(field, inner_hits: inner_hits,
+                                           max_concurrent_group_searches: max_concurrent_group_searches)
+      self
+    end
+
+    def search_after(values)
+      @search_after = AST::SearchAfter.new(values)
+      self
+    end
+
+    def combined_fields(query, fields, operator: nil, minimum_should_match: nil, **)
+      @nodes << AST::CombinedFields.new(query, fields, operator: operator, minimum_should_match: minimum_should_match,
+                                                       **)
+      self
+    end
+
+    def geo_distance(field, lat:, lon:, distance:, **options)
+      # Create a special geo filter node
+      geo_filter = AST::Filter.new(field, {
+                                     geo_distance: {
+                                       distance: distance,
+                                       "#{field}": { lat: lat, lon: lon }
+                                     }.merge(options)
+                                   })
+      @nodes << geo_filter
+      self
+    end
+
+    # Vector/semantic search using embeddings (pgvector or OpenSearch knn)
+    # @param field [Symbol] The embedding column/field
+    # @param embedding [Array<Float>] The query embedding vector
+    # @param k [Integer] Number of nearest neighbors (default: 10)
+    # @param distance_metric [Symbol] :cosine, :l2, or :inner_product
+    def vector(field, embedding, k: 10, distance_metric: :cosine)
+      @nodes << AST::Vector.new(field, embedding, k: k, distance_metric: distance_metric)
+      self
+    end
+
+    alias knn vector
+    alias semantic_search vector
+
+    # Hybrid search combining text query with vector search
+    # @param text_query [String] The text query for BM25 matching
+    # @param embedding [Array<Float>] The query embedding vector
+    # @param field [Symbol] The embedding field name
+    # @param text_weight [Float] Weight for text search score (default: 0.5)
+    # @param vector_weight [Float] Weight for vector search score (default: 0.5)
+    # @param k [Integer] Number of nearest neighbors (default: 10)
+    def hybrid(text_query, embedding, field:, text_weight: 0.5, vector_weight: 0.5, k: 10)
+      vector_node = AST::Vector.new(field, embedding, k: k)
+      @hybrid = AST::Hybrid.new(text_query, vector_node, text_weight: text_weight, vector_weight: vector_weight)
+      self
+    end
+
+    # Apply a search pipeline (OpenSearch only)
+    # @param pipeline_name [String] Name of the search pipeline to use
+    def pipeline(pipeline_name)
+      @pipeline = pipeline_name
+      self
+    end
+
+    # Image search using visual similarity (Typesense only)
+    # @param field [Symbol] The image embedding field name
+    # @param image_data [String] Image URL or base64 encoded image
+    # @param k [Integer] Number of nearest neighbors (default: 10)
+    def image_search(field, image_data, k: 10)
+      @image_query = AST::ImageQuery.new(field, image_data, k: k)
+      self
+    end
+
+    # Conversational/RAG search (Typesense and Elasticsearch)
+    # @param model_id [String] The LLM model identifier
+    # @param conversation_id [String, nil] ID for multi-turn conversations
+    # @param system_prompt [String, nil] Custom system prompt
+    def conversational(model_id:, conversation_id: nil, system_prompt: nil)
+      @conversation = AST::Conversation.new(
+        model_id: model_id,
+        conversation_id: conversation_id,
+        system_prompt: system_prompt
+      )
+      self
+    end
+
+    alias rag conversational
+
+    # Join with another collection (Typesense only)
+    # @param collection [String, Symbol] The collection to join
+    # @param on [Hash] Join conditions
+    # @param include_fields [Array] Fields to include from joined collection
+    # @param strategy [Symbol] Join strategy :left or :inner
+    def join(collection, on:, include_fields: [], strategy: :left)
+      @joins << AST::Join.new(collection, on: on, include_fields: include_fields, strategy: strategy)
+      self
+    end
+
+    # Remove duplicate documents in Typesense union search results.
+    def remove_duplicates(value: true)
+      @remove_duplicates = if value.nil?
+                             nil
+                           else
+                             value ? true : false
+                           end
+      self
+    end
+
+    # Controls dynamic facet sampling behavior in Typesense.
+    def facet_sample_slope(value)
+      @facet_sample_slope = value
+      self
+    end
+
+    # Pin specific document IDs to fixed result positions in Typesense.
+    #
+    # Supported formats:
+    # - String: "id1:1,id2:2"
+    # - Hash: { "id1" => 1, "id2" => 2 }
+    # - Array of pairs: [["id1", 1], ["id2", 2]]
+    def pinned_hits(value)
+      @pinned_hits = normalize_pinned_hits(value)
+      self
+    end
+
+    def to_ast
+      filter_nodes = @nodes.select { |n| n.is_a?(AST::Filter) }
+      vector_nodes = @nodes.select { |n| n.is_a?(AST::Vector) }
+      must_nodes = @nodes.reject do |n|
+        n.is_a?(AST::Filter) || n.is_a?(AST::Sort) || n.is_a?(AST::Paginate) || n.is_a?(AST::Vector)
+      end
+      bool_node = AST::Bool.new(must: must_nodes, filter: filter_nodes)
+      sort_nodes     = @nodes.select { |n| n.is_a?(AST::Sort) }
+      paginate_node  = @nodes.find { |n| n.is_a?(AST::Paginate) }
+      AST::Root.new(
+        indexes: @indexes,
+        bool: bool_node,
+        sort: sort_nodes,
+        paginate: paginate_node,
+        vector: vector_nodes.first, # Only support one vector search per query for now
+        collapse: @collapse,
+        search_after: @search_after,
+        aggregations: @aggregations,
+        hybrid: @hybrid,
+        pipeline: @pipeline,
+        image_query: @image_query,
+        conversation: @conversation,
+        joins: @joins,
+        remove_duplicates: @remove_duplicates,
+        facet_sample_slope: @facet_sample_slope,
+        pinned_hits: @pinned_hits
+      )
+    end
+
+    private
+
+    def normalize_pinned_hits(value)
+      case value
+      when nil
+        nil
+      when String
+        value
+      when Hash
+        value.map { |id, position| "#{id}:#{position}" }.join(",")
+      when Array
+        value.map do |entry|
+          raise ArgumentError, "pinned_hits array entries must be [id, position]" unless entry.is_a?(Array) && entry.size == 2
+
+          "#{entry[0]}:#{entry[1]}"
+        end.join(",")
+      else
+        raise ArgumentError, "pinned_hits must be a String, Hash, or Array of [id, position]"
+      end
+    end
+
+    def determine_indexes(model)
+      # Check for search_index (plural array) first
+      return Array(model.search_index) if model.respond_to?(:search_index) && model.search_index&.any?
+
+      # Check for index_name (singular string) next
+      return [model.index_name] if model.respond_to?(:index_name) && model.index_name
+
+      # Fallback to pluralized model name
+      [model.name.demodulize.underscore.pluralize]
+    end
+  end
+end

data/lib/noiseless/railtie.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "instrumentation"
+require_relative "runtime_reset_middleware"
+
+module Noiseless
+  class Railtie < Rails::Railtie
+    railtie_name :noiseless
+
+    config.noiseless = ActiveSupport::OrderedOptions.new
+
+    initializer "noiseless.configure" do |_app|
+      # Load configuration from config/noiseless.yml
+      Noiseless.load_configuration!
+    end
+
+    initializer "noiseless.instrumentation" do |app|
+      # Attach log subscriber
+      Noiseless::LogSubscriber.attach_to :noiseless
+
+      # Include controller runtime tracking in ActionController
+      ActiveSupport.on_load(:action_controller) do
+        include Noiseless::ControllerRuntime
+      end
+
+      # Reset runtime tracking at the beginning of each request
+      app.middleware.use Noiseless::RuntimeResetMiddleware
+    end
+
+    generators do
+      require_relative "generators/application_search_generator"
+    end
+  end
+end