noiseless 0.0.0 → 0.1.0

data/lib/noiseless/adapters/postgresql.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "execution_modules/postgresql_execution"
+
+module Noiseless
+  module Adapters
+    # PostgreSQL adapter for noiseless - uses pg_trgm, unaccent, and pgvector
+    # Provides search capabilities using native PostgreSQL extensions as:
+    # - Fallback when OpenSearch/Elasticsearch is unavailable
+    # - Simple queries that don't need full search cluster overhead
+    # - Semantic/vector search via pgvector
+    #
+    # Required extensions:
+    #   CREATE EXTENSION IF NOT EXISTS pg_trgm;
+    #   CREATE EXTENSION IF NOT EXISTS unaccent;
+    #   CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;
+    #   CREATE EXTENSION IF NOT EXISTS vector;  -- for pgvector
+    #
+    class Postgresql < Adapter
+      include ExecutionModules::PostgresqlExecution
+
+      attr_reader :model_class_cache
+
+      def initialize(hosts: nil, **connection_params) # rubocop:disable Lint/UnusedMethodArgument
+        @connection_params = connection_params
+        @model_class_cache = {}
+
+        # Verify extensions on initialization (optional, can be disabled)
+        verify_extensions! unless connection_params[:skip_extension_check]
+
+        super(hosts: [], **connection_params)
+      end
+
+      def async_context?
+        # PostgreSQL queries don't need async HTTP context
+        # but we still wrap in Async for consistency with other adapters
+        false
+      end
+
+      # Override AST conversion to build PostgreSQL-compatible query
+      def ast_to_hash(ast_node)
+        {
+          bool: ast_node.bool,
+          sort: ast_node.sort,
+          paginate: ast_node.paginate,
+          indexes: ast_node.indexes,  # maps to table/model
+          vector: ast_node.vector     # for pgvector semantic search
+        }
+      end
+
+      # Override search to return synchronously (no HTTP calls needed)
+      def search(ast_node, model_class: nil, response_type: nil, **)
+        query_hash = ast_to_hash(ast_node)
+
+        Async do
+          raw_response = instrument(:search, indexes: ast_node.indexes, query: query_hash) do
+            execute_search(query_hash, model_class: model_class, **)
+          end
+
+          ResponseFactory.create(
+            raw_response,
+            model_class: model_class,
+            response_type: response_type,
+            query_hash: build_pagination_from_ast(ast_node)
+          )
+        end
+      end
+
+      # Register model for this adapter (caches table info)
+      def register_model(model_class, index_name:)
+        @model_class_cache[index_name] = model_class
+      end
+
+      # Cluster health check - always healthy for PostgreSQL
+      def cluster
+        @cluster ||= ClusterAPI.new(self)
+      end
+
+      # Index operations - no-op for PostgreSQL (data lives in tables)
+      def indices
+        @indices ||= IndicesAPI.new(self)
+      end
+
+      class ClusterAPI
+        def initialize(adapter)
+          @adapter = adapter
+        end
+
+        def health(**)
+          # Check PostgreSQL connectivity and extensions
+          {
+            "cluster_name" => "postgresql",
+            "status" => @adapter.extensions_available? ? "green" : "yellow",
+            "number_of_nodes" => 1,
+            "active_primary_shards" => 1,
+            "extensions" => @adapter.available_extensions
+          }
+        end
+      end
+
+      class IndicesAPI
+        def initialize(adapter)
+          @adapter = adapter
+        end
+
+        def get(index:)
+          # Return table info as index info
+          { index => { "mappings" => {}, "settings" => {} } }
+        end
+
+        def stats(index:)
+          { "indices" => { index => {} } }
+        end
+
+        def refresh(index:) # rubocop:disable Lint/UnusedMethodArgument
+          # No-op for PostgreSQL - queries always see latest data
+          { "_shards" => { "total" => 1, "successful" => 1, "failed" => 0 } }
+        end
+      end
+
+      def extensions_available?
+        @extensions_available ||= check_extensions
+      end
+
+      def available_extensions
+        @available_extensions ||= detect_extensions
+      end
+
+      private
+
+      def verify_extensions!
+        missing = required_extensions - available_extensions
+        return if missing.empty?
+
+        Rails.logger.warn(
+          "Noiseless PostgreSQL adapter: Missing extensions: #{missing.join(', ')}. " \
+          "Some search features may be limited."
+        )
+      end
+
+      def required_extensions
+        %w[pg_trgm unaccent]
+      end
+
+      def check_extensions
+        required_extensions.all? { |ext| available_extensions.include?(ext) }
+      end
+
+      def detect_extensions
+        result = ActiveRecord::Base.connection.execute(<<~SQL.squish)
+          SELECT extname FROM pg_extension
+          WHERE extname IN ('pg_trgm', 'unaccent', 'fuzzystrmatch', 'vector', 'btree_gin', 'btree_gist')
+        SQL
+        result.pluck("extname")
+      rescue StandardError => e
+        Rails.logger.error("Failed to detect PostgreSQL extensions: #{e.message}")
+        []
+      end
+
+      def build_pagination_from_ast(ast_node)
+        paginate = ast_node.paginate
+        return { from: 0, size: 20 } unless paginate
+
+        {
+          from: (paginate.page - 1) * paginate.per_page,
+          size: paginate.per_page
+        }
+      end
+    end
+  end
+end

data/lib/noiseless/adapters/typesense.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "execution_modules/typesense_execution"
+
+module Noiseless
+  module Adapters
+    class Typesense < Adapter
+      include ExecutionModules::TypesenseExecution
+
+      def initialize(hosts: [], **connection_params)
+        # Ensure we always have at least one host
+        hosts_array = Array(hosts)
+        default_port = ENV["TYPESENSE_PORT"] || 8108
+        @hosts = hosts_array.empty? ? ["http://localhost:#{default_port}"] : hosts_array
+        @connection_params = connection_params
+
+        # Initialize HTTP clients for each host
+        @clients = {}
+        @hosts.each do |host|
+          endpoint = Async::HTTP::Endpoint.parse(host)
+          @clients[host] = Async::HTTP::Client.new(endpoint)
+        end
+
+        super(hosts: @hosts, **connection_params)
+      end
+
+      # Cluster health API - needed for Rails healthcheck
+      def cluster
+        @cluster ||= ClusterAPI.new(self)
+      end
+
+      # Indices API - needed for index management operations
+      def indices
+        @indices ||= IndicesAPI.new(self)
+      end
+
+      class ClusterAPI
+        def initialize(adapter)
+          @adapter = adapter
+        end
+
+        def health(**)
+          Sync do
+            @adapter.send(:execute_cluster_health, **)
+          end
+        end
+      end
+
+      class IndicesAPI
+        def initialize(adapter)
+          @adapter = adapter
+        end
+
+        def get(index:)
+          @adapter.execute_index_exists?(index) ? { index => {} } : raise("Index not found")
+        end
+
+        def stats(index:)
+          # Return basic stats structure
+          { "indices" => { index => {} } }
+        end
+
+        def refresh(index: nil) # rubocop:disable Lint/UnusedMethodArgument
+          # Typesense doesn't require explicit refresh - documents are immediately available
+          { "_shards" => { "total" => 1, "successful" => 1, "failed" => 0 } }
+        end
+      end
+    end
+  end
+end

data/lib/noiseless/adapters.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module Adapters
+    def self.lookup(name, hosts: [], **params)
+      adapter_name = name.to_s
+      class_name = adapter_name.classify
+
+      # Zeitwerk will load the adapter class on demand
+      adapter_class = const_get(class_name)
+      adapter_class.new(hosts: hosts, **params)
+    end
+  end
+end

data/lib/noiseless/ast/aggregation.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class Aggregation < Node
+      attr_reader :name, :type, :field, :options, :sub_aggregations
+
+      METRIC_TYPES = %i[avg sum min max cardinality value_count stats extended_stats percentiles].freeze
+      BUCKET_TYPES = %i[terms histogram date_histogram range date_range filter filters nested].freeze
+
+      def initialize(name, type, field: nil, sub_aggregations: [], **options)
+        super()
+        @name = name.to_s
+        @type = type.to_sym
+        @field = field&.to_s
+        @options = options
+        @sub_aggregations = sub_aggregations
+      end
+
+      def metric?
+        METRIC_TYPES.include?(@type)
+      end
+
+      def bucket?
+        BUCKET_TYPES.include?(@type)
+      end
+
+      def add_sub_aggregation(aggregation)
+        @sub_aggregations << aggregation
+      end
+    end
+
+    class AggregationBuilder
+      attr_reader :aggregations
+
+      def initialize
+        @aggregations = []
+      end
+
+      def agg(name, type, field: nil, **, &)
+        sub_aggs = []
+        if block_given?
+          sub_builder = AggregationBuilder.new
+          sub_builder.instance_eval(&)
+          sub_aggs = sub_builder.aggregations
+        end
+
+        aggregation = Aggregation.new(name, type, field: field, sub_aggregations: sub_aggs, **)
+        @aggregations << aggregation
+        aggregation
+      end
+
+      alias aggregation agg
+    end
+  end
+end

data/lib/noiseless/ast/bool.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class Bool < Node
+      attr_reader :must, :filter, :should
+
+      def initialize(must: [], filter: [], should: [])
+        super()
+        @must = must
+        @filter = filter
+        @should = should
+      end
+    end
+  end
+end

data/lib/noiseless/ast/bulk.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class Bulk < Node
+      attr_reader :operations
+
+      def initialize(operations)
+        super()
+        @operations = operations
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && operations == other.operations
+      end
+    end
+  end
+end

data/lib/noiseless/ast/collapse.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class Collapse < Node
+      attr_reader :field, :inner_hits, :max_concurrent_group_searches
+
+      def initialize(field, inner_hits: nil, max_concurrent_group_searches: nil)
+        super()
+        @field = field.to_s
+        @inner_hits = inner_hits
+        @max_concurrent_group_searches = max_concurrent_group_searches
+      end
+    end
+  end
+end

data/lib/noiseless/ast/combined_fields.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class CombinedFields < Node
+      attr_reader :query, :fields, :operator, :minimum_should_match, :zero_terms_query,
+                  :auto_generate_synonyms_phrase_query
+
+      def initialize(query, fields, operator: nil, minimum_should_match: nil, zero_terms_query: nil,
+                     auto_generate_synonyms_phrase_query: nil)
+        super()
+        @query = query
+        @fields = Array(fields).map(&:to_s)
+        @operator = operator
+        @minimum_should_match = minimum_should_match
+        @zero_terms_query = zero_terms_query
+        @auto_generate_synonyms_phrase_query = auto_generate_synonyms_phrase_query
+      end
+
+      def options
+        {}.tap do |opts|
+          opts[:operator] = @operator if @operator
+          opts[:minimum_should_match] = @minimum_should_match if @minimum_should_match
+          opts[:zero_terms_query] = @zero_terms_query if @zero_terms_query
+          unless @auto_generate_synonyms_phrase_query.nil?
+            opts[:auto_generate_synonyms_phrase_query] =
+              @auto_generate_synonyms_phrase_query
+          end
+        end
+      end
+    end
+  end
+end

data/lib/noiseless/ast/conversation.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    # Conversational search node for RAG (Retrieval Augmented Generation)
+    # Typesense and Elasticsearch support conversational/RAG search
+    class Conversation < Node
+      attr_reader :model_id, :conversation_id, :system_prompt
+
+      # @param model_id [String] The LLM model identifier
+      # @param conversation_id [String, nil] ID for multi-turn conversations (optional)
+      # @param system_prompt [String, nil] Custom system prompt (optional)
+      def initialize(model_id:, conversation_id: nil, system_prompt: nil)
+        super()
+        @model_id = model_id
+        @conversation_id = conversation_id
+        @system_prompt = system_prompt
+      end
+
+      def multi_turn?
+        !@conversation_id.nil?
+      end
+
+      def custom_prompt?
+        !@system_prompt.nil?
+      end
+    end
+  end
+end

data/lib/noiseless/ast/filter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class Filter < Node
+      attr_reader :field, :value
+
+      def initialize(field, value)
+        super()
+        @field = field
+        @value = value
+      end
+    end
+  end
+end

data/lib/noiseless/ast/hybrid.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    # Hybrid search node combining text and vector search
+    # Supports weighted combination of BM25 text scores and kNN vector scores
+    class Hybrid < Node
+      attr_reader :text_query, :vector, :text_weight, :vector_weight
+
+      # @param text_query [String] The text query for BM25 matching
+      # @param vector [AST::Vector] The vector search node
+      # @param text_weight [Float] Weight for text search score (0.0-1.0)
+      # @param vector_weight [Float] Weight for vector search score (0.0-1.0)
+      def initialize(text_query, vector, text_weight: 0.5, vector_weight: 0.5)
+        super()
+        @text_query = text_query
+        @vector = vector
+        @text_weight = text_weight
+        @vector_weight = vector_weight
+      end
+
+      def balanced?
+        @text_weight == @vector_weight
+      end
+
+      def text_dominant?
+        @text_weight > @vector_weight
+      end
+
+      def vector_dominant?
+        @vector_weight > @text_weight
+      end
+    end
+  end
+end

data/lib/noiseless/ast/image_query.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    # Image search node for Typesense visual search
+    # Supports searching by image URL or base64 encoded image data
+    class ImageQuery < Node
+      attr_reader :field, :image_data, :k
+
+      # @param field [Symbol, String] The image embedding field name
+      # @param image_data [String] Image URL or base64 encoded image data
+      # @param k [Integer] Number of nearest neighbors (default: 10)
+      def initialize(field, image_data, k: 10)
+        super()
+        @field = field
+        @image_data = image_data
+        @k = k
+      end
+
+      def url?
+        @image_data.start_with?("http://", "https://")
+      end
+
+      def base64?
+        !url?
+      end
+    end
+  end
+end

data/lib/noiseless/ast/join.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    # Join node for cross-collection queries (Typesense feature)
+    # Allows including related documents from other collections
+    class Join < Node
+      attr_reader :collection, :on, :include_fields, :strategy
+
+      # @param collection [String, Symbol] The collection to join
+      # @param on [Hash] Join conditions (e.g., { foreign_key: :local_key })
+      # @param include_fields [Array<String, Symbol>] Fields to include from joined collection
+      # @param strategy [Symbol] Join strategy :left or :inner (default: :left)
+      def initialize(collection, on:, include_fields: [], strategy: :left)
+        super()
+        @collection = collection.to_s
+        @on = on
+        @include_fields = Array(include_fields).map(&:to_s)
+        @strategy = strategy
+      end
+
+      def left_join?
+        @strategy == :left
+      end
+
+      def inner_join?
+        @strategy == :inner
+      end
+    end
+  end
+end

data/lib/noiseless/ast/match.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class Match < Node
+      attr_reader :field, :value
+
+      def initialize(field, value)
+        super()
+        @field = field
+        @value = value
+      end
+    end
+  end
+end

data/lib/noiseless/ast/multi_match.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class MultiMatch
+      attr_reader :query, :fields, :options
+
+      def initialize(query, fields, **options)
+        @query = query
+        @fields = Array(fields)
+        @options = options
+      end
+
+      def to_hash
+        {
+          multi_match: {
+            query: @query,
+            fields: @fields
+          }.merge(@options)
+        }
+      end
+    end
+  end
+end

data/lib/noiseless/ast/paginate.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class Paginate < Node
+      attr_reader :page, :per_page
+
+      def initialize(page, per_page)
+        super()
+        @page = page
+        @per_page = per_page
+      end
+    end
+  end
+end

data/lib/noiseless/ast/prefix.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class Prefix < Node
+      attr_reader :field, :value
+
+      def initialize(field, value)
+        super()
+        @field = field
+        @value = value
+      end
+    end
+  end
+end

data/lib/noiseless/ast/range.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module AST
+    class Range < Node
+      attr_reader :field, :gte, :lte, :gt, :lt
+
+      def initialize(field, gte: nil, lte: nil, gt: nil, lt: nil)
+        super()
+        @field = field
+        @gte = gte
+        @lte = lte
+        @gt = gt
+        @lt = lt
+      end
+    end
+  end
+end