noiseless 0.0.0 → 0.1.0

data/lib/noiseless/introspection.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module Introspection
+    # Runtime adapter and module detection
+    def adapter_info
+      {
+        adapter_type: self.class.name.split("::").last.underscore.to_sym,
+        execution_mode: :async,
+        execution_module: detect_execution_module,
+        capabilities: adapter_capabilities,
+        engine_name: engine_name
+      }
+    end
+
+    def detect_execution_module
+      execution_modules = singleton_class.included_modules.select do |mod|
+        mod.name&.include?("ExecutionModules") ||
+          mod.name&.include?("Execution")
+      end
+
+      execution_modules.map do |mod|
+        {
+          name: mod.name,
+          async: true
+        }
+      end
+    end
+
+    def adapter_capabilities
+      capabilities = [:async_support]
+
+      # Check for bulk operations
+      capabilities << :bulk_operations if respond_to?(:bulk)
+
+      # Check for search operations
+      capabilities << :search if respond_to?(:search)
+
+      # Check for index management
+      capabilities << :index_management if respond_to?(:create_index)
+
+      # Check for document operations
+      capabilities << :document_operations if respond_to?(:index_document)
+
+      # Engine-specific capabilities
+      case self.class.name
+      when /OpenSearch/
+        capabilities += %i[point_in_time_search search_templates] if respond_to?(:point_in_time_search)
+      when /Typesense/
+        capabilities += %i[typo_tolerance faceted_search] if respond_to?(:faceted_search)
+      when /Elasticsearch/
+        capabilities += %i[aggregations percolate] if respond_to?(:percolate)
+      end
+
+      capabilities.uniq
+    end
+
+    def engine_name
+      case self.class.name
+      when /OpenSearch/ then :opensearch
+      when /Elasticsearch/ then :elasticsearch
+      when /Typesense/ then :typesense
+      else :base
+      end
+    end
+
+    # Query execution introspection
+    def explain_query(ast_node, **)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      explanation = {
+        adapter: adapter_info,
+        ast: ast_node.to_h,
+        engine_query: nil,
+        execution_plan: [],
+        performance: {}
+      }
+
+      # Convert AST to engine query
+      conversion_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      engine_query = ast_to_hash(ast_node)
+      conversion_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - conversion_start
+
+      explanation[:engine_query] = engine_query
+      explanation[:performance][:ast_conversion_ms] = (conversion_time * 1000).round(3)
+
+      # Build execution plan
+      explanation[:execution_plan] = build_execution_plan(ast_node, **)
+
+      total_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      explanation[:performance][:total_explanation_ms] = (total_time * 1000).round(3)
+
+      explanation
+    end
+
+    def build_execution_plan(_ast_node, **_opts)
+      plan = []
+
+      plan << {
+        step: "ast_validation",
+        description: "Validate AST structure",
+        estimated_cost: "O(n) where n = AST node count"
+      }
+
+      plan << {
+        step: "query_conversion",
+        description: "Convert AST to #{engine_name} query format",
+        estimated_cost: "O(n) where n = AST complexity"
+      }
+
+      plan << {
+        step: "async_task_creation",
+        description: "Wrap execution in Async::Task",
+        estimated_cost: "O(1)"
+      }
+
+      plan << {
+        step: "engine_execution",
+        description: "Execute query on #{engine_name}",
+        estimated_cost: "Variable - depends on query complexity and data size"
+      }
+
+      plan << {
+        step: "response_processing",
+        description: "Convert engine response to Noiseless format",
+        estimated_cost: "O(m) where m = result count"
+      }
+
+      plan
+    end
+
+    # Cross-engine compatibility analysis
+    def compatibility_matrix
+      available_adapters = [
+        Noiseless::Adapters::Elasticsearch,
+        Noiseless::Adapters::OpenSearch,
+        Noiseless::Adapters::Typesense
+      ]
+
+      matrix = {}
+
+      available_adapters.each do |adapter_class|
+        adapter = adapter_class.new
+        adapter_name = adapter.engine_name
+
+        matrix[:"#{adapter_name}_async"] = {
+          available: true,
+          capabilities: adapter.adapter_capabilities,
+          engine_name: adapter.engine_name
+        }
+      rescue StandardError => e
+        fallback_key = adapter_class.name.split("::").last.underscore
+        matrix[:"#{fallback_key}_async"] = {
+          available: false,
+          error: e.message
+        }
+      end
+
+      matrix
+    end
+
+    # Performance profiling
+    def profile_query(ast_node, iterations: 100, **)
+      results = {
+        adapter: adapter_info,
+        iterations: iterations,
+        measurements: [],
+        summary: {}
+      }
+
+      iterations.times do |_i|
+        measurement = measure_single_execution(ast_node, **)
+        results[:measurements] << measurement
+      end
+
+      # Calculate summary statistics
+      times = results[:measurements].map { |m| m[:total_time_ms] }
+      results[:summary] = {
+        min_ms: times.min,
+        max_ms: times.max,
+        avg_ms: (times.sum / times.size).round(3),
+        median_ms: times.sort[times.size / 2],
+        std_dev_ms: calculate_std_dev(times).round(3)
+      }
+
+      results
+    end
+
+    private
+
+    def measure_single_execution(ast_node, **_opts)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # Convert AST
+      conversion_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      _engine_query = ast_to_hash(ast_node)
+      conversion_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - conversion_start
+
+      # Execute (mock execution for testing)
+      execution_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      sleep(0.001) # Simulate async execution
+      execution_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - execution_start
+
+      total_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+      {
+        ast_conversion_ms: (conversion_time * 1000).round(3),
+        execution_ms: (execution_time * 1000).round(3),
+        total_time_ms: (total_time * 1000).round(3)
+      }
+    end
+
+    def calculate_std_dev(values)
+      return 0.0 if values.size <= 1
+
+      mean = values.sum / values.size.to_f
+      variance = values.sum { |v| (v - mean)**2 } / (values.size - 1).to_f
+      Math.sqrt(variance)
+    end
+  end
+end

data/lib/noiseless/mapping.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Noiseless
+  class Mapping
+    class << self
+      def inherited(subclass)
+        super
+        # Inherit mappings and settings from parent class
+        subclass.instance_variable_set(:@mapping_definition, @mapping_definition&.dup)
+        subclass.instance_variable_set(:@index_settings, @index_settings&.dup)
+        subclass.instance_variable_set(:@analyzers, @analyzers&.dup)
+      end
+
+      def mapping(&)
+        if block_given?
+          @mapping_definition = MappingDefinition.new
+          @mapping_definition.instance_eval(&)
+        end
+        @mapping_definition
+      end
+
+      def settings(settings_hash = nil, &)
+        if settings_hash
+          @index_settings = (@index_settings || {}).merge(settings_hash)
+        elsif block_given?
+          @index_settings ||= {}
+          builder = SettingsBuilder.new(@index_settings)
+          builder.instance_eval(&)
+        end
+        @index_settings
+      end
+
+      def analyzer(name, definition)
+        @analyzers ||= {}
+        @analyzers[name.to_s] = definition
+      end
+
+      def analyzers
+        @analyzers || {}
+      end
+
+      def index_name(name = nil)
+        @index_name = name.to_s if name
+        @index_name
+      end
+
+      def to_mapping_hash
+        return {} unless @mapping_definition
+
+        { properties: @mapping_definition.to_hash }
+      end
+
+      def to_settings_hash
+        settings = @index_settings || {}
+
+        # Add analyzers to settings if any are defined
+        if @analyzers&.any?
+          settings = settings.deep_merge(
+            analysis: {
+              analyzer: @analyzers
+            }
+          )
+        end
+
+        settings
+      end
+
+      def load_settings_from_file(file_path)
+        return unless File.exist?(file_path)
+
+        content = File.read(file_path)
+        parsed_settings = case File.extname(file_path)
+                          when ".json"
+                            JSON.parse(content)
+                          when ".yml", ".yaml"
+                            YAML.load(content)
+                          else
+                            raise ArgumentError, "Unsupported file format: #{File.extname(file_path)}"
+                          end
+
+        settings(parsed_settings)
+      end
+    end
+
+    # Instance methods
+    def initialize(document)
+      @document = document
+    end
+
+    def to_h
+      if @document.respond_to?(:to_search_document)
+        @document.to_search_document
+      elsif @document.respond_to?(:to_h)
+        @document.to_h
+      elsif @document.respond_to?(:attributes)
+        @document.attributes
+      else
+        @document
+      end
+    end
+
+    def self.deserialize(hit)
+      hit["_source"]
+    end
+  end
+
+  # DSL for building mapping definitions
+  class MappingDefinition
+    def initialize
+      @properties = {}
+    end
+
+    def field(name, type, **options)
+      @properties[name.to_s] = { type: type.to_s }.merge(options)
+    end
+
+    def keyword(name, **)
+      field(name, :keyword, **)
+    end
+
+    def text(name, **)
+      field(name, :text, **)
+    end
+
+    def integer(name, **)
+      field(name, :integer, **)
+    end
+
+    def long(name, **)
+      field(name, :long, **)
+    end
+
+    def float(name, **)
+      field(name, :float, **)
+    end
+
+    def double(name, **)
+      field(name, :double, **)
+    end
+
+    def boolean(name, **)
+      field(name, :boolean, **)
+    end
+
+    def date(name, **)
+      field(name, :date, **)
+    end
+
+    def geo_point(name, **)
+      field(name, :geo_point, **)
+    end
+
+    def object(name, **, &)
+      if block_given?
+        nested_mapping = MappingDefinition.new
+        nested_mapping.instance_eval(&)
+        field(name, :object, properties: nested_mapping.to_hash, **)
+      else
+        field(name, :object, **)
+      end
+    end
+
+    def nested(name, **, &)
+      if block_given?
+        nested_mapping = MappingDefinition.new
+        nested_mapping.instance_eval(&)
+        field(name, :nested, properties: nested_mapping.to_hash, **)
+      else
+        field(name, :nested, **)
+      end
+    end
+
+    def to_hash
+      @properties
+    end
+  end
+
+  # DSL for building settings
+  class SettingsBuilder
+    def initialize(settings_hash)
+      @settings = settings_hash
+    end
+
+    def number_of_shards(count)
+      @settings[:number_of_shards] = count
+    end
+
+    def number_of_replicas(count)
+      @settings[:number_of_replicas] = count
+    end
+
+    def refresh_interval(interval)
+      @settings[:refresh_interval] = interval
+    end
+
+    def max_result_window(size)
+      @settings[:max_result_window] = size
+    end
+
+    def analysis(&)
+      @settings[:analysis] ||= {}
+      builder = AnalysisBuilder.new(@settings[:analysis])
+      builder.instance_eval(&)
+    end
+  end
+
+  # DSL for analysis settings
+  class AnalysisBuilder
+    def initialize(analysis_hash)
+      @analysis = analysis_hash
+    end
+
+    def analyzer(name, &)
+      @analysis[:analyzer] ||= {}
+      builder = AnalyzerBuilder.new
+      builder.instance_eval(&)
+      @analysis[:analyzer][name.to_s] = builder.to_hash
+    end
+
+    def tokenizer(name, definition)
+      @analysis[:tokenizer] ||= {}
+      @analysis[:tokenizer][name.to_s] = definition
+    end
+
+    def filter(name, definition)
+      @analysis[:filter] ||= {}
+      @analysis[:filter][name.to_s] = definition
+    end
+  end
+
+  # DSL for analyzer definition
+  class AnalyzerBuilder
+    def initialize
+      @definition = {}
+    end
+
+    def tokenizer(name)
+      @definition[:tokenizer] = name.to_s
+    end
+
+    def filter(*names)
+      @definition[:filter] = names.map(&:to_s)
+    end
+
+    def char_filter(*names)
+      @definition[:char_filter] = names.map(&:to_s)
+    end
+
+    def to_hash
+      @definition
+    end
+  end
+end

data/lib/noiseless/mapping_definition_processor.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Noiseless
+  class MappingDefinitionProcessor
+    def self.process(mapping_block)
+      return {} unless mapping_block
+
+      processor = new
+      processor.instance_eval(&mapping_block)
+      processor.to_index_config
+    end
+
+    def initialize
+      @settings = {}
+      @properties = {}
+    end
+
+    def settings(&)
+      settings_builder = SettingsBuilder.new
+      settings_builder.instance_eval(&)
+      @settings = settings_builder.to_hash
+    end
+
+    def properties(&)
+      properties_builder = PropertiesBuilder.new
+      properties_builder.instance_eval(&)
+      @properties = properties_builder.to_hash
+    end
+
+    # Delegate to settings builder for nested methods
+    def analysis(&)
+      settings { analysis(&) }
+    end
+
+    def to_index_config
+      config = {}
+      config[:settings] = @settings unless @settings.empty?
+      config[:mappings] = { properties: @properties } unless @properties.empty?
+      config
+    end
+
+    class SettingsBuilder
+      def initialize
+        @settings = {}
+      end
+
+      def index(&)
+        index_builder = IndexSettingsBuilder.new
+        index_builder.instance_eval(&)
+        @settings[:index] = index_builder.to_hash
+      end
+
+      def analysis(&)
+        analysis_builder = AnalysisBuilder.new
+        analysis_builder.instance_eval(&)
+        @settings[:analysis] = analysis_builder.to_hash
+      end
+
+      def to_hash
+        @settings
+      end
+    end
+
+    class IndexSettingsBuilder
+      def initialize
+        @index_settings = {}
+      end
+
+      def analysis(&)
+        analysis_builder = AnalysisBuilder.new
+        analysis_builder.instance_eval(&)
+        @index_settings[:analysis] = analysis_builder.to_hash
+      end
+
+      def to_hash
+        @index_settings
+      end
+    end
+
+    class AnalysisBuilder
+      def initialize
+        @analysis = {}
+      end
+
+      def normalizer(name = nil, &)
+        @analysis[:normalizer] ||= {}
+        if name && block_given?
+          # Define a specific normalizer
+          normalizer_builder = NormalizerBuilder.new
+          normalizer_builder.instance_eval(&)
+          @analysis[:normalizer][name] = normalizer_builder.to_hash
+        elsif block_given?
+          # Handle nested normalizer definitions
+          normalizer_definitions = NormalizerDefinitions.new
+          normalizer_definitions.instance_eval(&)
+          @analysis[:normalizer].merge!(normalizer_definitions.to_hash)
+        end
+      end
+
+      def analyzer(name = nil, &)
+        @analysis[:analyzer] ||= {}
+        if name && block_given?
+          # Define a specific analyzer
+          analyzer_builder = AnalyzerBuilder.new
+          analyzer_builder.instance_eval(&)
+          @analysis[:analyzer][name] = analyzer_builder.to_hash
+        elsif block_given?
+          # Handle nested analyzer definitions
+          analyzer_definitions = AnalyzerDefinitions.new
+          analyzer_definitions.instance_eval(&)
+          @analysis[:analyzer].merge!(analyzer_definitions.to_hash)
+        end
+      end
+
+      def to_hash
+        @analysis
+      end
+    end
+
+    class NormalizerBuilder
+      def initialize
+        @config = {}
+      end
+
+      def type(value)
+        @config[:type] = value
+      end
+
+      def char_filter(filters)
+        @config[:char_filter] = filters
+      end
+
+      def filter(filters)
+        @config[:filter] = filters
+      end
+
+      def to_hash
+        @config
+      end
+    end
+
+    class AnalyzerDefinitions
+      def initialize
+        @analyzers = {}
+      end
+
+      def method_missing(name, &)
+        if block_given?
+          analyzer_builder = AnalyzerBuilder.new
+          analyzer_builder.instance_eval(&)
+          @analyzers[name] = analyzer_builder.to_hash
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(_name, _include_private = false)
+        true
+      end
+
+      def to_hash
+        @analyzers
+      end
+    end
+
+    class NormalizerDefinitions
+      def initialize
+        @normalizers = {}
+      end
+
+      def method_missing(name, &)
+        if block_given?
+          normalizer_builder = NormalizerBuilder.new
+          normalizer_builder.instance_eval(&)
+          @normalizers[name] = normalizer_builder.to_hash
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(_name, _include_private = false)
+        true
+      end
+
+      def to_hash
+        @normalizers
+      end
+    end
+
+    class AnalyzerBuilder
+      def initialize
+        @config = {}
+      end
+
+      def type(value)
+        @config[:type] = value
+      end
+
+      def stopwords(value)
+        @config[:stopwords] = value
+      end
+
+      def filter(filters)
+        @config[:filter] = filters
+      end
+
+      def to_hash
+        @config
+      end
+    end
+
+    class PropertiesBuilder
+      def initialize
+        @properties = {}
+      end
+
+      # Define a property with a symbol name and type
+      def method_missing(name, type_or_field, options = {})
+        @properties[name] = { type: type_or_field }.merge(options)
+      end
+
+      def respond_to_missing?(_name, _include_private = false)
+        true
+      end
+
+      def to_hash
+        @properties
+      end
+    end
+  end
+end