prescient 0.7.0 → 0.8.0

data/lib/prescient/base.rb

@@ -1,429 +1,427 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'net/http'
-
-# Base class for all AI provider implementations
-#
-# This abstract base class defines the common interface that all AI providers
-# must implement. It provides shared functionality for text processing, context
-# formatting, prompt building, and error handling.
-#
-# @abstract Subclass and implement {#generate_embedding}, {#generate_response},
-#   {#health_check}, and any configuration validation required by
-#   {#validate_configuration!}
-#
-# @example Creating a custom provider
-#   class MyProvider < Prescient::Base
-#     def generate_embedding(text, **options)
-#       # Implementation here
-#     end
-#
-#     def generate_response(prompt, context_items = [], **options)
-#       # Implementation here
-#     end
-#
-#     def health_check
-#       # Implementation here
-#     end
-#   end
-#
-class Prescient::Base
-  # @return [Hash] Configuration options for this provider instance
-  attr_reader :options, :provider_name
-
-  # Initialize the provider with configuration options
-  #
-  # @param options [Hash] Provider-specific configuration options
-  # @option options [String] :api_key API key for authenticated providers
-  # @option options [String] :url Base URL for self-hosted providers
-  # @option options [Integer] :timeout Request timeout in seconds
-  # @option options [Hash] :prompt_templates Custom prompt templates
-  # @option options [Hash] :context_configs Context formatting configurations
-  # @option options [Integer] :embedding_dimensions Expected custom embedding size
-  # @option options [Array<Symbol, String>] :context_excluded_fields Additional
-  #   field names excluded from generic embedding text
-  def initialize(**options)
-    @options = options
-    @provider_name = options.fetch(:provider_name, self.class.to_s.split('::').last).to_s.sub(/\A./, &:upcase)
-    validate_configuration!
-  end
-
-  # Generate embeddings for the given text
-  #
-  # This method must be implemented by subclasses to provide embedding
-  # generation functionality.
-  #
-  # @param text [String] The text to generate embeddings for
-  # @param options [Hash] Provider-specific options
-  # @return [Array<Float>] Array of embedding values
-  # @raise [NotImplementedError] If not implemented by subclass
-  # @abstract
-  def generate_embedding(text, **options)
-    raise NotImplementedError, "#{self.class} must implement #generate_embedding"
-  end
+require "json"
+require "net/http"
 
-  # Generate text response for the given prompt
+module Prescient
+  # Base class for all AI provider implementations
   #
-  # This method must be implemented by subclasses to provide text generation
-  # functionality with optional context items.
+  # This abstract base class defines the common interface that all AI providers
+  # must implement. It provides shared functionality for text processing, context
+  # formatting, prompt building, and error handling.
   #
-  # @param prompt [String] The prompt to generate a response for
-  # @param context_items [Array<Hash, String>] Optional context items to include
-  # @param options [Hash] Provider-specific generation options
-  # @option options [Float] :temperature Sampling temperature (0.0-2.0)
-  # @option options [Integer] :max_tokens Maximum tokens to generate
-  # @option options [Float] :top_p Nucleus sampling parameter
-  # @return [Hash] Response hash with :response, :model, :provider keys
-  # @raise [NotImplementedError] If not implemented by subclass
-  # @abstract
-  def generate_response(prompt, context_items = [], **options)
-    raise NotImplementedError, "#{self.class} must implement #generate_response"
-  end
-
-  # Check the health and availability of the provider
+  # @abstract Subclass and implement {#generate_embedding}, {#generate_response},
+  #   {#health_check}, and any configuration validation required by
+  #   {#validate_configuration!}
   #
-  # This method must be implemented by subclasses to provide health check
-  # functionality.
+  # @example Creating a custom provider
+  #   class MyProvider < Prescient::Base
+  #     def generate_embedding(text, **options)
+  #       # Implementation here
+  #     end
   #
-  # @return [Hash] Health status with at least :status and :provider keys,
-  #   and typically :reachable and :ready for modern adapters
-  # @raise [NotImplementedError] If not implemented by subclass
-  # @abstract
-  def health_check
-    raise NotImplementedError, "#{self.class} must implement #health_check"
-  end
-
-  # Check if the provider is currently available
+  #     def generate_response(prompt, context_items = [], **options)
+  #       # Implementation here
+  #     end
   #
-  # Returns `true` when the health check reports `reachable: true`.
-  # For legacy adapters that only return a status string, `status == "healthy"`
-  # is also treated as available.
+  #     def health_check
+  #       # Implementation here
+  #     end
+  #   end
   #
-  # @return [Boolean] true if the provider is currently reachable
-  def available?
-    health = health_check
-    health.key?(:reachable) ? health[:reachable] == true : health[:status] == 'healthy'
-  rescue StandardError
-    false
-  end
-
-  protected
+  # rubocop:disable Metrics/ClassLength
+  class Base
+    # @return [Hash] Configuration options for this provider instance
+    attr_reader :options, :provider_name
+
+    # Initialize the provider with configuration options
+    #
+    # @param options [Hash] Provider-specific configuration options
+    # @option options [String] :api_key API key for authenticated providers
+    # @option options [String] :url Base URL for self-hosted providers
+    # @option options [Integer] :timeout Request timeout in seconds
+    # @option options [Hash] :prompt_templates Custom prompt templates
+    # @option options [Hash] :context_configs Context formatting configurations
+    # @option options [Integer] :embedding_dimensions Expected custom embedding size
+    # @option options [Array<Symbol, String>] :context_excluded_fields Additional
+    #   field names excluded from generic embedding text
+    def initialize(**options)
+      @options = options
+      @provider_name = options.fetch(:provider_name, self.class.to_s.split("::").last).to_s.sub(/\A./, &:upcase)
+      validate_configuration!
+    end
 
-  # Validate provider configuration
-  #
-  # Override this method in subclasses to validate required configuration
-  # options and raise appropriate errors for missing or invalid settings.
-  #
-  # @return [void]
-  # @raise [Prescient::Error] If configuration is invalid
-  def validate_configuration!
-    # Override in subclasses to validate required configuration
-  end
+    # Generate embeddings for the given text
+    #
+    # This method must be implemented by subclasses to provide embedding
+    # generation functionality.
+    #
+    # @param text [String] The text to generate embeddings for
+    # @param options [Hash] Provider-specific options
+    # @return [Array<Float>] Array of embedding values
+    # @raise [NotImplementedError] If not implemented by subclass
+    # @abstract
+    def generate_embedding(text, **options)
+      raise NotImplementedError, "#{self.class} must implement #generate_embedding"
+    end
 
-  # Handle and standardize errors from provider operations
-  #
-  # Wraps provider-specific operations and converts common exceptions
-  # into standardized Prescient error types while preserving existing
-  # Prescient errors.
-  #
-  # @yield The operation block to execute with error handling
-  # @return [Object] The result of the yielded block
-  # @raise [Prescient::ConnectionError] For network/timeout errors
-  # @raise [Prescient::InvalidResponseError] For JSON parsing errors
-  # @raise [Prescient::Error] For other unexpected errors
-  def handle_errors
-    yield
-  rescue Prescient::Error
-    # Re-raise Prescient errors without wrapping
-    raise
-  rescue Net::ReadTimeout, Net::OpenTimeout => e
-    raise Prescient::ConnectionError, "Request timeout: #{e.message}"
-  rescue Net::HTTPError => e
-    raise Prescient::ConnectionError, "HTTP error: #{e.message}"
-  rescue JSON::ParserError => e
-    raise Prescient::InvalidResponseError, "Invalid JSON response: #{e.message}"
-  rescue StandardError => e
-    raise Prescient::Error, "Unexpected error: #{e.message}"
-  end
+    # Generate text response for the given prompt
+    #
+    # This method must be implemented by subclasses to provide text generation
+    # functionality with optional context items.
+    #
+    # @param prompt [String] The prompt to generate a response for
+    # @param context_items [Array<Hash, String>] Optional context items to include
+    # @param options [Hash] Provider-specific generation options
+    # @option options [Float] :temperature Sampling temperature (0.0-2.0)
+    # @option options [Integer] :max_tokens Maximum tokens to generate
+    # @option options [Float] :top_p Nucleus sampling parameter
+    # @return [Hash] Response hash with :response, :model, :provider keys
+    # @raise [NotImplementedError] If not implemented by subclass
+    # @abstract
+    def generate_response(prompt, context_items = [], **options)
+      raise NotImplementedError, "#{self.class} must implement #generate_response"
+    end
 
-  # Validate embedding dimensions against the configured model dimension.
-  #
-  # Embedding dimensions are part of the vector-storage contract. Vectors are
-  # never padded or truncated because either operation changes their meaning.
-  #
-  # @param embedding [Array<Float>] The embedding vector to validate
-  # @param target_dimensions [Integer] The required number of dimensions
-  # @return [Array<Float>] The original embedding when dimensions are valid
-  # @raise [Prescient::InvalidResponseError] If the vector is malformed or has
-  #   an unexpected dimension
-  def validate_embedding_dimensions(embedding, target_dimensions)
-    raise Prescient::InvalidResponseError, 'Embedding response is not an array' unless embedding.is_a?(Array)
-
-    return embedding if embedding.length == target_dimensions
-
-    raise Prescient::InvalidResponseError,
-          "Invalid embedding dimensions: expected #{target_dimensions}, got #{embedding.length}"
-  end
+    # Check the health and availability of the provider
+    #
+    # This method must be implemented by subclasses to provide health check
+    # functionality.
+    #
+    # @return [Hash] Health status with at least :status and :provider keys,
+    #   and typically :reachable and :ready for modern adapters
+    # @raise [NotImplementedError] If not implemented by subclass
+    # @abstract
+    def health_check
+      raise NotImplementedError, "#{self.class} must implement #health_check"
+    end
 
-  # Clean and preprocess text for AI processing
-  #
-  # Removes excess whitespace, normalizes spacing, and truncates to the
-  # library's current 8,000-character input ceiling.
-  #
-  # @param text [String, nil] The text to clean
-  # @return [String] Cleaned text, empty string if input was nil/empty
-  def clean_text(text)
-    # Limit length for most models
-    text.to_s.gsub(/\s+/, ' ').strip.slice(0, 8000)
-  end
+    # Check if the provider is currently available
+    #
+    # Returns `true` when the health check reports `reachable: true`.
+    # For legacy adapters that only return a status string, `status == "healthy"`
+    # is also treated as available.
+    #
+    # @return [Boolean] true if the provider is currently reachable
+    def available?
+      health = health_check
+      health.key?(:reachable) ? health[:reachable] == true : health[:status] == "healthy"
+    rescue StandardError
+      false
+    end
 
-  # Get default prompt templates
-  #
-  # Provides standard templates for system prompts and context handling
-  # that can be overridden via provider options.
-  #
-  # @return [Hash] Hash containing template strings with placeholders
-  # @private
-  def default_prompt_templates
-    {
-      system_prompt:         'You are a helpful AI assistant. Answer questions clearly and accurately.',
-      no_context_template:   <<~TEMPLATE.strip,
-        %<system_prompt>s
+    protected
+
+    # Validate provider configuration
+    #
+    # Override this method in subclasses to validate required configuration
+    # options and raise appropriate errors for missing or invalid settings.
+    #
+    # @return [void]
+    # @raise [Prescient::Error] If configuration is invalid
+    def validate_configuration!
+      # Override in subclasses to validate required configuration
+    end
 
-        Question: %<query>s
+    # Handle and standardize errors from provider operations
+    #
+    # Wraps provider-specific operations and converts common exceptions
+    # into standardized Prescient error types while preserving existing
+    # Prescient errors.
+    #
+    # @yield The operation block to execute with error handling
+    # @return [Object] The result of the yielded block
+    # @raise [Prescient::ConnectionError] For network/timeout errors
+    # @raise [Prescient::InvalidResponseError] For JSON parsing errors
+    # @raise [Prescient::Error] For other unexpected errors
+    def handle_errors
+      yield
+    rescue Prescient::Error
+      # Re-raise Prescient errors without wrapping
+      raise
+    rescue Net::ReadTimeout, Net::OpenTimeout => e
+      raise Prescient::ConnectionError, "Request timeout: #{e.message}"
+    rescue Net::HTTPError => e
+      raise Prescient::ConnectionError, "HTTP error: #{e.message}"
+    rescue JSON::ParserError => e
+      raise Prescient::InvalidResponseError, "Invalid JSON response: #{e.message}"
+    rescue StandardError => e
+      raise Prescient::Error, "Unexpected error: #{e.message}"
+    end
 
-        Please provide a helpful response based on your knowledge.
-      TEMPLATE
-      with_context_template: <<~TEMPLATE.strip,
-        %<system_prompt>s Use the following context to answer the question. If the context doesn't contain relevant information, say so clearly.
+    # Validate embedding dimensions against the configured model dimension.
+    #
+    # Embedding dimensions are part of the vector-storage contract. Vectors are
+    # never padded or truncated because either operation changes their meaning.
+    #
+    # @param embedding [Array<Float>] The embedding vector to validate
+    # @param target_dimensions [Integer] The required number of dimensions
+    # @return [Array<Float>] The original embedding when dimensions are valid
+    # @raise [Prescient::InvalidResponseError] If the vector is malformed or has
+    #   an unexpected dimension
+    def validate_embedding_dimensions(embedding, target_dimensions)
+      raise Prescient::InvalidResponseError, "Embedding response is not an array" unless embedding.is_a?(Array)
+
+      return embedding if embedding.length == target_dimensions
+
+      raise Prescient::InvalidResponseError,
+            "Invalid embedding dimensions: expected #{target_dimensions}, got #{embedding.length}"
+    end
 
-        Context:
-        %<context>s
+    # Clean and preprocess text for AI processing
+    #
+    # Removes excess whitespace, normalizes spacing, and truncates to the
+    # library's current 8,000-character input ceiling.
+    #
+    # @param text [String, nil] The text to clean
+    # @return [String] Cleaned text, empty string if input was nil/empty
+    def clean_text(text)
+      # Limit length for most models
+      text.to_s.gsub(/\s+/, " ").strip.slice(0, 8000)
+    end
 
-        Question: %<query>s
+    # Get default prompt templates
+    #
+    # Provides standard templates for system prompts and context handling
+    # that can be overridden via provider options.
+    #
+    # @return [Hash] Hash containing template strings with placeholders
+    # @private
+    def default_prompt_templates
+      {
+        system_prompt: "You are a helpful AI assistant. Answer questions clearly and accurately.",
+        no_context_template: <<~TEMPLATE.strip,
+          %<system_prompt>s
+
+          Question: %<query>s
+
+          Please provide a helpful response based on your knowledge.
+        TEMPLATE
+        with_context_template: <<~TEMPLATE.strip
+          %<system_prompt>s Use the following context to answer the question. If the context doesn't contain relevant information, say so clearly.
+
+          Context:
+          %<context>s
+
+          Question: %<query>s
+
+          Please provide a helpful response based on the context above.
+        TEMPLATE
+      }
+    end
 
-        Please provide a helpful response based on the context above.
-      TEMPLATE
-    }
-  end
+    # Build formatted prompt from query and context items
+    #
+    # Creates a properly formatted prompt using configurable templates,
+    # incorporating context items when provided.
+    #
+    # @param query [String] The user's question or prompt
+    # @param context_items [Array<Hash, String>] Optional context items
+    # @return [String] Formatted prompt ready for AI processing
+    def build_prompt(query, context_items = [])
+      templates = default_prompt_templates.merge(@options[:prompt_templates] || {})
+      system_prompt = templates[:system_prompt]
+
+      if context_items.empty?
+        format(templates[:no_context_template], system_prompt: system_prompt, query: query)
+      else
+        context_text = context_items.map.with_index(1) do |item, index|
+          "#{index}. #{format_context_item(item)}"
+        end.join("\n\n")
+
+        format(templates[:with_context_template], system_prompt: system_prompt, context: context_text,
+                                                  query: query)
+      end
+    end
 
-  # Build formatted prompt from query and context items
-  #
-  # Creates a properly formatted prompt using configurable templates,
-  # incorporating context items when provided.
-  #
-  # @param query [String] The user's question or prompt
-  # @param context_items [Array<Hash, String>] Optional context items
-  # @return [String] Formatted prompt ready for AI processing
-  def build_prompt(query, context_items = [])
-    templates = default_prompt_templates.merge(@options[:prompt_templates] || {})
-    system_prompt = templates[:system_prompt]
-
-    if context_items.empty?
-      templates[:no_context_template] % {
-        system_prompt: system_prompt,
-        query:         query,
-      }
-    else
-      context_text = context_items.map.with_index(1) { |item, index|
-        "#{index}. #{format_context_item(item)}"
-      }.join("\n\n")
-
-      templates[:with_context_template] % {
-        system_prompt: system_prompt,
-        context:       context_text,
-        query:         query,
+    # Minimal default context configuration - users should define their own contexts
+    def default_context_configs
+      embedding_fields = [] # : Array[untyped]
+      fields = [] # : Array[untyped]
+
+      {
+        # Generic fallback configuration - works with any hash structure
+        "default" => {
+          fields: fields, # Will be dynamically determined from item keys
+          format: nil, # Will use fallback formatting
+          embedding_fields: embedding_fields # Will use all string/text fields
+        }
       }
     end
-  end
-
-  # Minimal default context configuration - users should define their own contexts
-  def default_context_configs
-    embedding_fields = [] # : Array[untyped]
-    fields = [] # : Array[untyped]
-
-    {
-      # Generic fallback configuration - works with any hash structure
-      'default' => {
-        fields:           fields, # Will be dynamically determined from item keys
-        format:           nil, # Will use fallback formatting
-        embedding_fields: embedding_fields, # Will use all string/text fields
-      },
-    }
-  end
 
-  # Extract text for embedding generation based on context configuration
-  def extract_embedding_text(item, context_type = nil)
-    return item.to_s unless item.is_a?(Hash)
+    # Extract text for embedding generation based on context configuration
+    def extract_embedding_text(item, context_type = nil)
+      return item.to_s unless item.is_a?(Hash)
 
-    config = resolve_context_config(item, context_type)
-    text_values = extract_configured_fields(item, config) || extract_text_values(item)
-    text_values.join(' ').strip
-  end
+      config = resolve_context_config(item, context_type)
+      text_values = extract_configured_fields(item, config) || extract_text_values(item)
+      text_values.join(" ").strip
+    end
 
-  # Extract text values from hash, excluding non-textual fields
-  def extract_text_values(item)
-    # Common fields to exclude from embedding text. Provider-specific fields can
-    # be added with the :context_excluded_fields option.
-    default_excluded_fields = ['id', '_id', 'uuid', 'created_at', 'updated_at', 'timestamp', 'version', 'status',
-                               'active']
-    configured_fields = Array(@options[:context_excluded_fields]) # : Array[untyped]
-    configured_excluded_fields = configured_fields.map { |field| field.to_s.downcase }
-    exclude_fields = default_excluded_fields | configured_excluded_fields
-
-    item.filter_map { |key, value|
-      next if exclude_fields.include?(key.to_s.downcase)
-      next unless value.is_a?(String) || value.is_a?(Numeric)
-      next if value.to_s.strip.empty?
-
-      value.to_s
-    }
-  end
+    # Extract text values from hash, excluding non-textual fields
+    def extract_text_values(item)
+      # Common fields to exclude from embedding text. Provider-specific fields can
+      # be added with the :context_excluded_fields option.
+      default_excluded_fields = %w[id _id uuid created_at updated_at timestamp version status
+                                   active]
+      configured_fields = Array(@options[:context_excluded_fields]) # : Array[untyped]
+      configured_excluded_fields = configured_fields.map { |field| field.to_s.downcase }
+      exclude_fields = default_excluded_fields | configured_excluded_fields
+
+      item.filter_map do |key, value|
+        next if exclude_fields.include?(key.to_s.downcase)
+        next unless value.is_a?(String) || value.is_a?(Numeric)
+        next if value.to_s.strip.empty?
+
+        value.to_s
+      end
+    end
 
-  # Generic context item formatting using configurable contexts
-  def format_context_item(item)
-    case item
-    when Hash then format_hash_item(item)
-    when String then item
-    else item.to_s
+    # Generic context item formatting using configurable contexts
+    def format_context_item(item)
+      case item
+      when Hash then format_hash_item(item)
+      when String then item
+      else item.to_s
+      end
     end
-  end
 
-  private
+    private
 
-  # Resolve context configuration for an item
-  def resolve_context_config(item, context_type)
-    context_configs = default_context_configs.merge(@options[:context_configs] || {})
-    return context_configs['default'] if context_configs.empty?
+    # Resolve context configuration for an item
+    def resolve_context_config(item, context_type)
+      context_configs = default_context_configs.merge(@options[:context_configs] || {})
+      return context_configs["default"] if context_configs.empty?
 
-    detected_type = context_type || detect_context_type(item)
-    context_configs[detected_type] || context_configs['default']
-  end
+      detected_type = context_type || detect_context_type(item)
+      context_configs[detected_type] || context_configs["default"]
+    end
 
-  # Extract fields configured for embeddings
-  def extract_configured_fields(item, config)
-    return nil unless config[:embedding_fields]&.any?
+    # Extract fields configured for embeddings
+    def extract_configured_fields(item, config)
+      return nil unless config[:embedding_fields]&.any?
 
-    config[:embedding_fields].filter_map { |field| item[field] || item[field.to_sym] }
-  end
+      config[:embedding_fields].filter_map { |field| item[field] || item[field.to_sym] }
+    end
 
-  # Format a hash item using context configuration
-  def format_hash_item(item)
-    config = resolve_context_config(item, nil)
-    return fallback_format_hash(item) unless config[:format]
+    # Format a hash item using context configuration
+    def format_hash_item(item)
+      config = resolve_context_config(item, nil)
+      return fallback_format_hash(item) unless config[:format]
 
-    format_data = build_format_data(item, config)
-    return fallback_format_hash(item) unless format_data.any?
+      format_data = build_format_data(item, config)
+      return fallback_format_hash(item) unless format_data.any?
 
-    apply_format_template(config[:format], format_data) || fallback_format_hash(item)
-  end
+      apply_format_template(config[:format], format_data) || fallback_format_hash(item)
+    end
+
+    # Build format data from item fields
+    def build_format_data(item, config)
+      format_data = {} # : Hash[Symbol, untyped]
+      fields_to_check = config[:fields].any? ? config[:fields] : item.keys.map(&:to_s)
 
-  # Build format data from item fields
-  def build_format_data(item, config)
-    format_data = {} # : Hash[Symbol, untyped]
-    fields_to_check = config[:fields].any? ? config[:fields] : item.keys.map(&:to_s)
+      fields_to_check.each do |field|
+        value = item[field] || item[field.to_sym]
+        format_data[field.to_sym] = value if value
+      end
 
-    fields_to_check.each do |field|
-      value = item[field] || item[field.to_sym]
-      format_data[field.to_sym] = value if value
+      format_data
     end
 
-    format_data
-  end
+    # Apply format template with error handling
+    def apply_format_template(template, format_data)
+      template % format_data
+    rescue KeyError
+      nil
+    end
 
-  # Apply format template with error handling
-  def apply_format_template(template, format_data)
-    template % format_data
-  rescue KeyError
-    nil
-  end
+    # Detect context type from item structure
+    def detect_context_type(item)
+      return "default" unless item.is_a?(Hash)
 
-  # Detect context type from item structure
-  def detect_context_type(item)
-    return 'default' unless item.is_a?(Hash)
+      # Check for explicit type fields (user-defined)
+      return item["type"].to_s if item["type"]
+      return item["context_type"].to_s if item["context_type"]
+      return item["model_type"].to_s.downcase if item["model_type"]
 
-    # Check for explicit type fields (user-defined)
-    return item['type'].to_s if item['type']
-    return item['context_type'].to_s if item['context_type']
-    return item['model_type'].to_s.downcase if item['model_type']
+      # If no explicit type and user has configured contexts, try to match
+      context_configs = @options[:context_configs] || {}
+      return match_context_by_fields(item, context_configs) if context_configs.any?
 
-    # If no explicit type and user has configured contexts, try to match
-    context_configs = @options[:context_configs] || {}
-    return match_context_by_fields(item, context_configs) if context_configs.any?
+      # Default fallback
+      "default"
+    end
 
-    # Default fallback
-    'default'
-  end
+    # Match context type based on configured field patterns
+    def match_context_by_fields(item, context_configs)
+      item_fields = item.keys.map(&:to_s)
+      best_match = find_best_field_match(item_fields, context_configs)
+      best_match || "default"
+    end
 
-  # Match context type based on configured field patterns
-  def match_context_by_fields(item, context_configs)
-    item_fields = item.keys.map(&:to_s)
-    best_match = find_best_field_match(item_fields, context_configs)
-    best_match || 'default'
-  end
+    # Find the best matching context configuration
+    def find_best_field_match(item_fields, context_configs)
+      best_match = nil
+      best_score = 0
 
-  # Find the best matching context configuration
-  def find_best_field_match(item_fields, context_configs)
-    best_match = nil
-    best_score = 0
+      context_configs.each do |context_type, config|
+        next unless config[:fields]&.any?
 
-    context_configs.each do |context_type, config|
-      next unless config[:fields]&.any?
+        score = calculate_field_match_score(item_fields, config[:fields])
+        next unless score >= 0.5 && score > best_score
 
-      score = calculate_field_match_score(item_fields, config[:fields])
-      next unless score >= 0.5 && score > best_score
+        best_match = context_type
+        best_score = score
+      end
 
-      best_match = context_type
-      best_score = score
+      best_match
     end
 
-    best_match
-  end
-
-  # Calculate field matching score
-  def calculate_field_match_score(item_fields, config_fields)
-    return 0 if config_fields.empty?
+    # Calculate field matching score
+    def calculate_field_match_score(item_fields, config_fields)
+      return 0 if config_fields.empty?
 
-    matching_fields = (item_fields & config_fields).size
-    matching_fields.to_f / config_fields.size
-  end
+      matching_fields = (item_fields & config_fields).size
+      matching_fields.to_f / config_fields.size
+    end
 
-  # Fallback formatting for hash items
-  def fallback_format_hash(item, format_data = nil)
-    # Fallback: join key-value pairs
-    (format_data || item).map { |k, v| "#{k}: #{v}" }.join(', ')
-  end
+    # Fallback formatting for hash items
+    def fallback_format_hash(item, format_data = nil)
+      # Fallback: join key-value pairs
+      (format_data || item).map { |k, v| "#{k}: #{v}" }.join(", ")
+    end
 
-  def validate_response!(response, operation)
-    return if response.success?
-
-    resp_message, error_class = case response.code
-                                when 400
-                                  ['Bad Request', Prescient::Error]
-                                when 401
-                                  ['Authentication Failure', Prescient::AuthenticationError]
-                                when 403
-                                  ['Forbidden Access', Prescient::AuthenticationError]
-                                when 404
-                                  ['Model Not Available', Prescient::ModelNotAvailableError]
-                                when 429
-                                  ['Rate Limit Exceeded', Prescient::RateLimitError]
-                                when 500..599
-                                  ["#{provider_name} Server Error", Prescient::ProviderError]
-                                else
-                                  ["#{provider_name} Request Failure", Prescient::Error]
-                                end
-
-    raise provider_error(resp_message, response, error_class:, operation:)
-  end
+    def validate_response!(response, operation)
+      return if response.success?
+
+      resp_message, error_class = case response.code
+                                  when 400
+                                    ["Bad Request", Prescient::Error]
+                                  when 401
+                                    ["Authentication Failure", Prescient::AuthenticationError]
+                                  when 403
+                                    ["Forbidden Access", Prescient::AuthenticationError]
+                                  when 404
+                                    ["Model Not Available", Prescient::ModelNotAvailableError]
+                                  when 429
+                                    ["Rate Limit Exceeded", Prescient::RateLimitError]
+                                  when 500..599
+                                    ["#{provider_name} Server Error", Prescient::ProviderError]
+                                  else
+                                    ["#{provider_name} Request Failure", Prescient::Error]
+                                  end
+
+      raise provider_error(resp_message, response, error_class:, operation:)
+    end
 
-  def provider_error(message, response, operation:, provider: nil, error_class: Prescient::ProviderError)
-    error_class.new(
-      message,
-      provider:  provider || provider_name,
-      operation:,
-      status:    response.code,
-    )
+    def provider_error(message, response, operation:, provider: nil, error_class: Prescient::ProviderError)
+      error_class.new(
+        message,
+        provider: provider || provider_name,
+        operation:,
+        status: response.code
+      )
+    end
   end
+  # rubocop:enable Metrics/ClassLength
 end