prescient 0.1.0 → 0.2.0

data/lib/prescient/base.rb

@@ -1,26 +1,95 @@
 # frozen_string_literal: true
 
+# 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 {#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
+#
+# @author Claude Code
+# @since 1.0.0
 class Prescient::Base
+  # @return [Hash] Configuration options for this provider instance
   attr_reader :options
 
+  # 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
   def initialize(**options)
     @options = options
     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 :status, :provider keys and optional details
+  # @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
+  #
+  # @return [Boolean] true if provider is healthy and available
   def available?
     health_check[:status] == 'healthy'
   rescue StandardError
@@ -29,10 +98,28 @@ class Prescient::Base
 
   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 +135,40 @@ class Prescient::Base
     raise Prescient::Error, "Unexpected error: #{e.message}"
   end
 
+  # Normalize embedding dimensions to match expected size
+  #
+  # Ensures embedding vectors have consistent dimensions by truncating
+  # longer vectors or padding shorter ones with zeros.
+  #
+  # @param embedding [Array<Float>] The embedding vector to normalize
+  # @param target_dimensions [Integer] The desired number of dimensions
+  # @return [Array<Float>, nil] Normalized embedding or nil if input invalid
   def normalize_embedding(embedding, target_dimensions)
     return nil unless embedding.is_a?(Array)
-    return embedding if embedding.length == target_dimensions
+    return embedding.first(target_dimensions) 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
+    embedding + Array.new(target_dimensions - embedding.length, 0.0)
   end
 
+  # Clean and preprocess text for AI processing
+  #
+  # Removes excess whitespace, normalizes spacing, and enforces length
+  # limits suitable for most AI models.
+  #
+  # @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 +192,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]
@@ -143,6 +246,7 @@ class Prescient::Base
   # Extract text values from hash, excluding non-textual fields
   def extract_text_values(item)
     # Common fields to exclude from embedding text
+    # TODO: configurable fields to exclude aside from the common ones below
     exclude_fields = ['id', '_id', 'uuid', 'created_at', 'updated_at', 'timestamp', 'version', 'status', 'active']
 
     item.filter_map { |key, value|

data/lib/prescient/client.rb

@@ -1,45 +1,107 @@
 # 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)
+  #
+  # @author Claude Code
+  # @since 1.0.0
   class Client
+    # @return [Symbol] The name of the provider being used
     attr_reader :provider_name
+
+    # @return [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
     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
     def health_check
       @provider.health_check
     end
 
+    # Check if the provider is currently available
+    #
+    # @return [Boolean] true if provider is healthy and available
     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, :options
     def provider_info
       {
         name:      @provider_name,
@@ -50,11 +112,7 @@ module Prescient
     end
 
     def method_missing(method_name, ...)
-      if @provider.respond_to?(method_name)
-        @provider.send(method_name, ...)
-      else
-        super
-      end
+      @provider.respond_to?(method_name) ? @provider.send(method_name, ...) : super
     end
 
     def respond_to_missing?(method_name, include_private = false)
@@ -63,6 +121,7 @@ module Prescient
 
     private
 
+    # TODO: configurable keys to sanitize
     def sanitize_options(options)
       sensitive_keys = [:api_key, :password, :token, :secret]
       options.reject { |key, _| sensitive_keys.include?(key.to_sym) }
@@ -86,22 +145,67 @@ 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|
+        # Use existing provider instance for primary provider, create new ones for fallbacks
+        provider = if index.zero? && provider_name == @provider_name
+                     @provider
+                   else
+                     Prescient.configuration.provider(provider_name)
+                   end
+        next unless provider
+
+        # Check if provider is available before trying
+        next unless provider.available?
+
+        # Use retry logic for each provider
+        return with_error_handling do
+          provider.send(method_name, *args, **options)
+        end
+      rescue Prescient::Error => e
+        last_error = e
+        # Log the error and continue to next provider
+        next
+      end
+
+      # If we get here, all providers failed
+      raise last_error || Prescient::Error.new("No available providers for #{method_name}")
+    end
+
+    def providers_to_try
+      providers = [@provider_name]
+
+      # Add configured fallback providers
+      fallback_providers = Prescient.configuration.fallback_providers
+      if fallback_providers && !fallback_providers.empty?
+        providers += fallback_providers.reject { |p| p == @provider_name }
+      else
+        # If no explicit fallbacks configured, try all available providers
+        available = Prescient.configuration.available_providers
+        providers += available.reject { |p| p == @provider_name }
+      end
+
+      providers.uniq
+    end
   end
 
   # Convenience methods for quick access
-  def self.client(provider_name = nil)
-    Client.new(provider_name)
+  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)
+  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)
+  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
 
   def self.health_check(provider: nil)
-    client(provider).health_check
+    client(provider, enable_fallback: false).health_check
   end
 end

data/lib/prescient/provider/huggingface.rb

@@ -157,9 +157,7 @@ class Prescient::Provider::HuggingFace < Prescient::Base
   protected
 
   def validate_configuration!
-    required_options = [:api_key, :embedding_model, :chat_model]
-    missing_options = required_options.select { |opt| @options[opt].nil? }
-
+    missing_options = [:api_key, :embedding_model, :chat_model].select { |opt| @options[opt].nil? }
     return unless missing_options.any?
 
     raise Prescient::Error, "Missing required options: #{missing_options.join(', ')}"

data/lib/prescient/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Prescient
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/prescient.rb

@@ -2,14 +2,50 @@
 
 require_relative 'prescient/version'
 
+# Main Prescient module for AI provider abstraction
+#
+# Prescient provides a unified interface for working with multiple AI providers
+# including Ollama, OpenAI, Anthropic, and HuggingFace. It supports both
+# embedding generation and text completion with configurable context handling.
+#
+# @example Basic usage
+#   Prescient.configure do |config|
+#     config.add_provider(:openai, Prescient::Provider::OpenAI,
+#                         api_key: 'your-api-key')
+#   end
+#
+#   client = Prescient.client(:openai)
+#   response = client.generate_response("Hello, world!")
+#
+# @example Embedding generation
+#   embedding = client.generate_embedding("Some text to embed")
+#   puts embedding.length # => 1536 (for OpenAI text-embedding-3-small)
+#
+# @author Claude Code
+# @since 1.0.0
 module Prescient
+  # Base error class for all Prescient-specific errors
   class Error < StandardError; 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
 
+  # 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
@@ -23,34 +59,85 @@ require_relative 'prescient/provider/huggingface'
 require_relative 'prescient/client'
 
 module Prescient
-  # Configure the gem
+  # Configure Prescient with custom settings and providers
+  #
+  # @example Configure with custom provider
+  #   Prescient.configure do |config|
+  #     config.default_provider = :openai
+  #     config.timeout = 60
+  #     config.add_provider(:openai, Prescient::Provider::OpenAI,
+  #                         api_key: 'your-key')
+  #   end
+  #
+  # @yield [config] Configuration block
+  # @yieldparam config [Configuration] The configuration object
+  # @return [void]
   def self.configure
     yield(configuration)
   end
 
+  # Get the current configuration instance
+  #
+  # @return [Configuration] The current configuration
   def self.configuration
     @_configuration ||= Configuration.new
   end
 
+  # Reset configuration to defaults
+  #
+  # @return [Configuration] New configuration instance
   def self.reset_configuration!
     @_configuration = Configuration.new
   end
 
+  # Configuration class for managing Prescient settings and providers
+  #
+  # Handles global settings like timeouts and retry behavior, as well as
+  # provider registration and instantiation.
   class Configuration
+    # @return [Symbol] The default provider to use when none specified
     attr_accessor :default_provider
+
+    # @return [Integer] Default timeout in seconds for API requests
     attr_accessor :timeout
+
+    # @return [Integer] Number of retry attempts for failed requests
     attr_accessor :retry_attempts
+
+    # @return [Float] Delay between retry attempts in seconds
     attr_accessor :retry_delay
+
+    # @return [Array<Symbol>] List of fallback providers to try when primary fails
+    attr_accessor :fallback_providers
+
+    # @return [Hash] Registered providers configuration
     attr_reader :providers
 
+    # Initialize configuration with default values
     def initialize
       @default_provider = :ollama
       @timeout = 30
       @retry_attempts = 3
       @retry_delay = 1.0
+      @fallback_providers = []
       @providers = {}
     end
 
+    # Register a new AI provider
+    #
+    # @param name [Symbol] Unique identifier for the provider
+    # @param provider_class [Class] Provider class that inherits from Base
+    # @param options [Hash] Configuration options for the provider
+    # @option options [String] :api_key API key for authenticated providers
+    # @option options [String] :url Base URL for self-hosted providers
+    # @option options [String] :model, :chat_model Model name for text generation
+    # @option options [String] :embedding_model Model name for embeddings
+    # @return [void]
+    #
+    # @example Add OpenAI provider
+    #   config.add_provider(:openai, Prescient::Provider::OpenAI,
+    #                       api_key: 'sk-...',
+    #                       chat_model: 'gpt-4')
     def add_provider(name, provider_class, **options)
       @providers[name.to_sym] = {
         class:   provider_class,
@@ -58,12 +145,27 @@ module Prescient
       }
     end
 
+    # Instantiate a provider by name
+    #
+    # @param name [Symbol] The provider name
+    # @return [Base, nil] Provider instance or nil if not found
     def provider(name)
       provider_config = @providers[name.to_sym]
       return nil unless provider_config
 
       provider_config[:class].new(**provider_config[:options])
     end
+
+    # Get list of available providers (those that are configured and healthy)
+    #
+    # @return [Array<Symbol>] List of available provider names
+    def available_providers
+      @providers.keys.select do |name|
+        provider(name)&.available?
+      rescue StandardError
+        false
+      end
+    end
   end
 
   # Default configuration

data/prescient.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "Prescient provides a unified interface for AI providers including local Ollama, Anthropic Claude, OpenAI GPT, and HuggingFace models. Built for AI applications with error handling, health monitoring, and provider switching."
   spec.homepage = "https://github.com/yourcompany/prescient"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.required_ruby_version = ">= 3.1.0"
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
   spec.metadata["homepage_uri"] = spec.homepage
@@ -31,21 +31,23 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Runtime dependencies
-  spec.add_dependency "httparty", "~> 0.22.0"
-  
+  spec.add_dependency "httparty", "~> 0.23.1"
+
   # Optional dependencies for vector database integration
-  spec.add_development_dependency "pg", "~> 1.5" # PostgreSQL adapter for pgvector integration
+  spec.add_development_dependency "pg", "~> 1.6" # PostgreSQL adapter for pgvector integration
 
   # Development dependencies
-  spec.add_development_dependency "minitest", "~> 5.20"
-  spec.add_development_dependency "mocha", "~> 2.1"
-  spec.add_development_dependency "webmock", "~> 3.18"
-  spec.add_development_dependency "vcr", "~> 6.1"
-  spec.add_development_dependency "rubocop", "~> 1.50"
-  spec.add_development_dependency "rubocop-minitest", "~> 0.35"
-  spec.add_development_dependency "rubocop-performance", "~> 1.19"
-  spec.add_development_dependency "rubocop-rake", "~> 0.6"
-  spec.add_development_dependency "simplecov", "~> 0.22"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "irb"
+  spec.add_development_dependency "minitest", "~> 5.25"
+  spec.add_development_dependency "mocha", "~> 2.7"
+  spec.add_development_dependency "webmock", "~> 3.25"
+  spec.add_development_dependency "vcr", "~> 6.3"
+  spec.add_development_dependency "rubocop", "~> 1.79"
+  spec.add_development_dependency "rubocop-minitest", "~> 0.38.1"
+  spec.add_development_dependency "rubocop-performance", "~> 1.25"
+  spec.add_development_dependency "rubocop-rake", "~> 0.7.1"
+  spec.add_development_dependency "simplecov", "~> 0.22.0"
+  spec.add_development_dependency "rake", "~> 13.3"
+  spec.add_development_dependency "irb", "~> 1.15"
+  spec.add_development_dependency "yard", "~> 0.9.37"
+  spec.add_development_dependency "kramdown", "~> 2.5"
 end