prescient 0.1.0 → 0.3.0

data/lib/prescient/base.rb

@@ -1,38 +1,137 @@
 # 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
-  attr_reader :options
-
+  # @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
 
-  # Abstract methods that must be implemented by subclasses
-  def generate_embedding(text)
+  # 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
 
+  # 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
 
+  # 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
 
+  # 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_check[:status] == 'healthy'
+    health = health_check
+    health.key?(:reachable) ? health[:reachable] == true : health[:status] == 'healthy'
   rescue StandardError
     false
   end
 
   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
 
+  # 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
@@ -48,31 +147,44 @@ class Prescient::Base
     raise Prescient::Error, "Unexpected error: #{e.message}"
   end
 
-  def normalize_embedding(embedding, target_dimensions)
-    return nil unless embedding.is_a?(Array)
+  # 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
 
-    if embedding.length > target_dimensions
-      # Truncate
-      embedding.first(target_dimensions)
-    else
-      # Pad with zeros
-      embedding + Array.new(target_dimensions - embedding.length, 0.0)
-    end
+    raise Prescient::InvalidResponseError,
+          "Invalid embedding dimensions: expected #{target_dimensions}, got #{embedding.length}"
   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)
-    return '' if text.nil? || text.to_s.strip.empty?
-
-    cleaned = text.to_s
-      .strip
-      .gsub(/\s+/, ' ')
-
     # Limit length for most models
-    cleaned.length > 8000 ? cleaned[0, 8000] : cleaned
+    text.to_s.gsub(/\s+/, ' ').strip.slice(0, 8000)
   end
 
-  # Default prompt templates - can be overridden in provider options
+  # 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.',
@@ -96,7 +208,14 @@ class Prescient::Base
     }
   end
 
-  # Build prompt using configurable templates
+  # 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]
@@ -121,12 +240,15 @@ class Prescient::Base
 
   # 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:           [], # Will be dynamically determined from item keys
+        fields:           fields, # Will be dynamically determined from item keys
         format:           nil, # Will use fallback formatting
-        embedding_fields: [], # Will use all string/text fields
+        embedding_fields: embedding_fields, # Will use all string/text fields
       },
     }
   end
@@ -142,8 +264,13 @@ class Prescient::Base
 
   # Extract text values from hash, excluding non-textual fields
   def extract_text_values(item)
-    # Common fields to exclude from embedding text
-    exclude_fields = ['id', '_id', 'uuid', 'created_at', 'updated_at', 'timestamp', 'version', 'status', 'active']
+    # 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)
@@ -194,7 +321,7 @@ class Prescient::Base
 
   # Build format data from item fields
   def build_format_data(item, config)
-    format_data = {}
+    format_data = {} # : Hash[Symbol, untyped]
     fields_to_check = config[:fields].any? ? config[:fields] : item.keys.map(&:to_s)
 
     fields_to_check.each do |field|
@@ -267,4 +394,36 @@ class Prescient::Base
     # 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 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

data/lib/prescient/client.rb

@@ -1,45 +1,106 @@
 # frozen_string_literal: true
 
 module Prescient
+  # Client class for interacting with AI providers
+  #
+  # The Client provides a high-level interface for working with AI providers,
+  # handling error recovery, retries, and method delegation. It acts as a
+  # facade over the configured providers.
+  #
+  # @example Basic usage
+  #   client = Prescient::Client.new(:openai)
+  #   response = client.generate_response("Hello, world!")
+  #   embedding = client.generate_embedding("Text to embed")
+  #
+  # @example Using default provider
+  #   client = Prescient::Client.new  # Uses configured default
+  #   puts client.provider_name       # => :ollama (or configured default)
+  #
   class Client
+    # @return [Symbol] The name of the provider being used
     attr_reader :provider_name
+
+    # @return [Prescient::Base] The underlying provider instance
     attr_reader :provider
 
-    def initialize(provider_name = nil)
+    # Initialize a new client with the specified provider
+    #
+    # @param provider_name [Symbol, nil] Name of provider to use, or nil for default
+    # @param enable_fallback [Boolean] Whether to enable automatic fallback to other providers
+    # @raise [Prescient::Error] If the specified provider is not configured
+    def initialize(provider_name = nil, enable_fallback: true)
       @provider_name = provider_name || Prescient.configuration.default_provider
       @provider = Prescient.configuration.provider(@provider_name)
+      @enable_fallback = enable_fallback
 
-      raise Prescient::Error, "Provider not found: #{@provider_name}" unless @provider
+      raise Prescient::Error, "Provider not configured: #{@provider_name}" unless @provider
     end
 
+    # Generate embeddings for the given text
+    #
+    # Delegates to the underlying provider with automatic retry logic
+    # for transient failures. If fallback is enabled, tries other providers
+    # on persistent failures.
+    #
+    # @param text [String] The text to generate embeddings for
+    # @param options [Hash] Provider-specific options
+    # @return [Array<Float>] Array of embedding values
+    # @raise [Prescient::Error] If embedding generation fails on all providers
     def generate_embedding(text, **options)
-      with_error_handling do
-        if options.any?
+      if @enable_fallback
+        with_fallback_handling(:generate_embedding, text, **options)
+      else
+        with_error_handling do
           @provider.generate_embedding(text, **options)
-        else
-          @provider.generate_embedding(text)
         end
       end
     end
 
+    # Generate text response for the given prompt
+    #
+    # Delegates to the underlying provider with automatic retry logic
+    # for transient failures. Supports optional context items for RAG.
+    # If fallback is enabled, tries other providers on persistent failures.
+    #
+    # @param prompt [String] The prompt to generate a response for
+    # @param context_items [Array<Hash, String>] Optional context items
+    # @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 [Prescient::Error] If response generation fails on all providers
     def generate_response(prompt, context_items = [], **options)
-      with_error_handling do
-        if options.any?
+      if @enable_fallback
+        with_fallback_handling(:generate_response, prompt, context_items, **options)
+      else
+        with_error_handling do
           @provider.generate_response(prompt, context_items, **options)
-        else
-          @provider.generate_response(prompt, context_items)
         end
       end
     end
 
+    # Check the health status of the provider
+    #
+    # @return [Hash] Health status information from the selected provider
     def health_check
       @provider.health_check
     end
 
+    # Check if the provider is currently available
+    #
+    # @return [Boolean] true if the provider currently passes its availability check
     def available?
       @provider.available?
     end
 
+    # Get comprehensive information about the provider
+    #
+    # Returns details about the provider including its availability
+    # and configuration options (with sensitive data removed).
+    #
+    # @return [Hash] Provider information including :name, :class, :available,
+    #   and recursively sanitized :options
     def provider_info
       {
         name:      @provider_name,
@@ -49,23 +110,25 @@ module Prescient
       }
     end
 
-    def method_missing(method_name, ...)
-      if @provider.respond_to?(method_name)
-        @provider.send(method_name, ...)
-      else
-        super
-      end
-    end
-
-    def respond_to_missing?(method_name, include_private = false)
-      @provider.respond_to?(method_name, include_private) || super
-    end
-
     private
 
     def sanitize_options(options)
-      sensitive_keys = [:api_key, :password, :token, :secret]
-      options.reject { |key, _| sensitive_keys.include?(key.to_sym) }
+      sensitive_keys = Prescient::Configuration::DEFAULT_SENSITIVE_KEYS + Prescient.configuration.sensitive_keys
+
+      case options
+      when Hash
+        sanitized = {} # : Hash[untyped, untyped]
+        options.each do |key, value|
+          next if key.respond_to?(:to_sym) && sensitive_keys.include?(key.to_sym)
+
+          sanitized[key] = sanitize_options(value)
+        end
+        sanitized
+      when Array
+        options.map { |value| sanitize_options(value) }
+      else
+        options
+      end
     end
 
     def with_error_handling
@@ -86,22 +149,97 @@ module Prescient
         retry
       end
     end
+
+    def with_fallback_handling(method_name, *args, **options)
+      last_error = nil
+
+      providers_to_try.each_with_index do |provider_name, index|
+        provider = provider_for(provider_name, index)
+        next unless provider
+
+        # Use the provider operation as the availability probe.
+        return with_error_handling do
+          provider.send(method_name, *args, **options)
+        end
+      rescue Prescient::Error => e
+        raise e unless fallback_eligible?(e)
+
+        last_error = e
+        next
+      end
+
+      # If we get here, all providers failed
+      raise last_error || Prescient::Error.new("No available providers for #{method_name}")
+    end
+
+    def provider_for(provider_name, index)
+      return @provider if index.zero? && provider_name == @provider_name
+
+      Prescient.configuration.provider(provider_name)
+    end
+
+    def providers_to_try
+      providers = [@provider_name]
+
+      # Add configured fallback providers
+      fallback_providers = Prescient.configuration.fallback_providers
+      additional_providers = if fallback_providers && !fallback_providers.empty?
+                               fallback_providers.reject { |p| p == @provider_name }
+                             else
+                               # If no explicit fallbacks are configured, probe all configured providers
+                               Prescient.configuration.providers.keys.reject { |p| p == @provider_name }
+                             end
+      providers += additional_providers
+
+      providers.uniq
+    end
+
+    def fallback_eligible?(error)
+      [
+        Prescient::ConnectionError,
+        Prescient::RateLimitError,
+        Prescient::ModelNotAvailableError,
+        Prescient::ProviderError,
+      ].any? { |error_class| error.is_a?(error_class) }
+    end
   end
 
   # Convenience methods for quick access
-  def self.client(provider_name = nil)
-    Client.new(provider_name)
+  #
+  # @param provider_name [Symbol, nil] Provider to use, or the configured default
+  # @param enable_fallback [Boolean] Whether provider fallback is enabled
+  # @return [Client] A configured client instance
+  def self.client(provider_name = nil, enable_fallback: true)
+    Client.new(provider_name, enable_fallback: enable_fallback)
   end
 
-  def self.generate_embedding(text, provider: nil, **options)
-    client(provider).generate_embedding(text, **options)
+  # Generate an embedding through a configured provider.
+  #
+  # @param text [String] Text to embed
+  # @param provider [Symbol, nil] Provider to use
+  # @param enable_fallback [Boolean] Whether provider fallback is enabled
+  # @return [Array<Float>] Embedding vector
+  def self.generate_embedding(text, provider: nil, enable_fallback: true, **options)
+    client(provider, enable_fallback: enable_fallback).generate_embedding(text, **options)
   end
 
-  def self.generate_response(prompt, context_items = [], provider: nil, **options)
-    client(provider).generate_response(prompt, context_items, **options)
+  # Generate a response through a configured provider.
+  #
+  # @param prompt [String] Prompt to send
+  # @param context_items [Array<Hash, String>] Optional context items
+  # @param provider [Symbol, nil] Provider to use
+  # @param enable_fallback [Boolean] Whether provider fallback is enabled
+  # @return [Hash] Normalized provider response with :response, :model, :provider
+  #   and optional metadata
+  def self.generate_response(prompt, context_items = [], provider: nil, enable_fallback: true, **options)
+    client(provider, enable_fallback: enable_fallback).generate_response(prompt, context_items, **options)
   end
 
+  # Return the health status of a configured provider.
+  #
+  # @param provider [Symbol, nil] Provider to check
+  # @return [Hash] Provider health information
   def self.health_check(provider: nil)
-    client(provider).health_check
+    client(provider, enable_fallback: false).health_check
   end
 end

data/lib/prescient/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Prescient
+  # Base error class for all Prescient-specific errors
+  class Error < StandardError
+    attr_reader :provider
+    attr_reader :operation
+    attr_reader :status
+
+    def initialize(message = nil, provider: nil, operation: nil, status: nil)
+      super(message)
+
+      @provider = provider
+      @operation = operation
+      @status = status
+    end
+  end
+
+  # Raised when there are connection issues with AI providers
+  class ConnectionError < Error; end
+
+  # Raised when API authentication fails
+  class AuthenticationError < Error; end
+
+  # Raised when API rate limits are exceeded
+  class RateLimitError < Error; end
+
+  # Raised when a requested model is not available
+  class ModelNotAvailableError < Error; end
+
+  # Raised when AI provider returns invalid or malformed responses
+  class InvalidResponseError < Error; end
+
+  # Raised when a vector cannot be stored or searched safely
+  class InvalidVectorError < Error; end
+
+  # Raised when an AI provider reports a transient service-side failure
+  class ProviderError < Error; end
+
+  # Container module for AI provider implementations
+  #
+  # All provider classes should be defined within this module and inherit
+  # from {Prescient::Base}.
+  module Provider
+    # Module for AI provider implementations
+  end
+
+  # Namespace for optional PostgreSQL pgvector integration
+  module Pgvector
+  end
+end