prescient 0.1.0 → 0.3.0

data/lib/prescient/provider/ollama.rb

@@ -2,33 +2,46 @@
 
 require 'httparty'
 
+# Ollama local or hosted API provider adapter.
 class Prescient::Provider::Ollama < Prescient::Base
   include HTTParty
 
-  EMBEDDING_DIMENSIONS = 768 # nomic-embed-text dimensions
-
   def initialize(**options)
     super
     self.class.base_uri(@options[:url])
     self.class.default_timeout(@options[:timeout] || 60)
   end
 
+  # Generate an embedding through Ollama's `/api/embed` endpoint.
+  # @param text [String] Text to embed
+  # @return [Array<Float>] Embedding vector from the first returned input item
   def generate_embedding(text, **_options)
     handle_errors do
-      embedding = fetch_and_parse('post', '/api/embeddings',
-                                  root_key: 'embedding',
-                                  headers:  { 'Content-Type' => 'application/json' },
-                                  body:     {
-                                    model:  @options[:embedding_model],
-                                    prompt: clean_text(text),
-                                  }.to_json)
-
-      raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding
-
-      normalize_embedding(embedding, EMBEDDING_DIMENSIONS)
+      embeddings = fetch_and_parse('post', '/api/embed',
+                                   root_key: 'embeddings',
+                                   headers:  { 'Content-Type' => 'application/json' },
+                                   body:     {
+                                     model: @options[:embedding_model],
+                                     input: clean_text(text),
+                                   }.to_json)
+
+      embedding = embeddings.is_a?(Array) ? embeddings.first : nil # : Array[Float]?
+      raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding.is_a?(Array)
+
+      expected_dimensions = @options[:embedding_dimensions]
+      if expected_dimensions && embedding.length != expected_dimensions
+        raise Prescient::InvalidResponseError,
+              "Invalid embedding dimensions: expected #{expected_dimensions}, got #{embedding.length}"
+      end
+
+      embedding
     end
   end
 
+  # Generate text through Ollama's generation endpoint.
+  # @param prompt [String] Prompt to send
+  # @param context_items [Array<Hash, String>] Optional context items
+  # @return [Hash] Normalized response data
   def generate_response(prompt, context_items = [], **options)
     handle_errors do
       request_options = prepare_generate_response(prompt, context_items, **options)
@@ -54,6 +67,12 @@ class Prescient::Provider::Ollama < Prescient::Base
     end
   end
 
+  # Check whether the configured Ollama models are available locally.
+  #
+  # `reachable` indicates the Ollama API answered successfully. `ready`
+  # indicates that both configured models are present in the local model list.
+  #
+  # @return [Hash] Provider health information
   def health_check
     handle_errors do
       models = available_models
@@ -63,6 +82,7 @@ class Prescient::Provider::Ollama < Prescient::Base
       {
         status:           'healthy',
         provider:         'ollama',
+        reachable:        true,
         url:              @options[:url],
         models_available: models.map { |m| m[:name] },
         embedding_model:  {
@@ -78,14 +98,19 @@ class Prescient::Provider::Ollama < Prescient::Base
     end
   rescue Prescient::Error => e
     {
-      status:   'unavailable',
-      provider: 'ollama',
-      error:    e.class.name,
-      message:  e.message,
-      url:      @options[:url],
+      status:    'unavailable',
+      provider:  'ollama',
+      reachable: false,
+      error:     e.class.name,
+      message:   e.message,
+      url:       @options[:url],
+      ready:     false,
     }
   end
 
+  # List models currently available from Ollama.
+  # @return [Array<Hash>] Model descriptors including name, size, digest,
+  #   modified_at, and booleans for configured embedding/chat roles
   def available_models
     return @_available_models if defined?(@_available_models)
 
@@ -98,6 +123,9 @@ class Prescient::Provider::Ollama < Prescient::Base
     end
   end
 
+  # Pull a model into the Ollama installation.
+  # @param model_name [String] Model identifier to download
+  # @return [Hash] Pull result
   def pull_model(model_name)
     handle_errors do
       fetch_and_parse('post', '/api/pull',
@@ -152,21 +180,4 @@ class Prescient::Provider::Ollama < Prescient::Base
     response.parsed_response[root_key]
   end
 
-  def validate_response!(response, operation)
-    return if response.success?
-
-    case response.code
-    when 404
-      raise Prescient::ModelNotAvailableError, "Model not available for #{operation}"
-    when 429
-      raise Prescient::RateLimitError, "Rate limit exceeded for #{operation}"
-    when 401, 403
-      raise Prescient::AuthenticationError, "Authentication failed for #{operation}"
-    when 500..599
-      raise Prescient::Error, "Ollama server error during #{operation}: #{response.body}"
-    else
-      raise Prescient::Error,
-            "Ollama request failed for #{operation}: HTTP #{response.code} - #{response.message}"
-    end
-  end
 end

data/lib/prescient/provider/openai.rb

@@ -2,11 +2,13 @@
 
 require 'httparty'
 
+# OpenAI API provider adapter.
 class Prescient::Provider::OpenAI < Prescient::Base
   include HTTParty
 
   base_uri 'https://api.openai.com'
 
+  # Known embedding dimensions for OpenAI embedding models.
   EMBEDDING_DIMENSIONS = {
     'text-embedding-3-small' => 1536,
     'text-embedding-3-large' => 3072,
@@ -18,6 +20,9 @@ class Prescient::Provider::OpenAI < Prescient::Base
     self.class.default_timeout(@options[:timeout] || 60)
   end
 
+  # Generate an embedding through the OpenAI embeddings API.
+  # @param text [String] Text to embed
+  # @return [Array<Float>] Embedding vector
   def generate_embedding(text, **_options)
     handle_errors do
       clean_text_input = clean_text(text)
@@ -38,11 +43,20 @@ class Prescient::Provider::OpenAI < Prescient::Base
       embedding_data = response.parsed_response.dig('data', 0, 'embedding')
       raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding_data
 
-      expected_dimensions = EMBEDDING_DIMENSIONS[@options[:embedding_model]] || 1536
-      normalize_embedding(embedding_data, expected_dimensions)
+      expected_dimensions = EMBEDDING_DIMENSIONS[@options[:embedding_model]] || @options[:embedding_dimensions]
+      unless expected_dimensions
+        raise Prescient::Error,
+              "Embedding dimensions are required for model #{@options[:embedding_model]}"
+      end
+
+      validate_embedding_dimensions(embedding_data, expected_dimensions)
     end
   end
 
+  # Generate a response through the OpenAI chat completions API.
+  # @param prompt [String] Prompt to send
+  # @param context_items [Array<Hash, String>] Optional context items
+  # @return [Hash] Normalized response data
   def generate_response(prompt, context_items = [], **options)
     handle_errors do
       formatted_prompt = build_prompt(prompt, context_items)
@@ -83,6 +97,12 @@ class Prescient::Provider::OpenAI < Prescient::Base
     end
   end
 
+  # Check OpenAI model availability via `/v1/models`.
+  #
+  # `reachable` indicates the API answered successfully. `ready` indicates that
+  # both configured models appear in the returned model list.
+  #
+  # @return [Hash] Provider health information
   def health_check
     handle_errors do
       response = self.class.get('/v1/models',
@@ -98,6 +118,7 @@ class Prescient::Provider::OpenAI < Prescient::Base
         {
           status:           'healthy',
           provider:         'openai',
+          reachable:        true,
           models_available: models.map { |m| m['id'] },
           embedding_model:  {
             name:      @options[:embedding_model],
@@ -111,22 +132,29 @@ class Prescient::Provider::OpenAI < Prescient::Base
         }
       else
         {
-          status:   'unhealthy',
-          provider: 'openai',
-          error:    "HTTP #{response.code}",
-          message:  response.message,
+          status:    'unhealthy',
+          provider:  'openai',
+          reachable: true,
+          error:     "HTTP #{response.code}",
+          message:   response.message,
+          ready:     false,
         }
       end
     end
   rescue Prescient::Error => e
     {
-      status:   'unavailable',
-      provider: 'openai',
-      error:    e.class.name,
-      message:  e.message,
+      status:    'unavailable',
+      provider:  'openai',
+      reachable: false,
+      error:     e.class.name,
+      message:   e.message,
+      ready:     false,
     }
   end
 
+  # List models available to the configured OpenAI account.
+  #
+  # @return [Array<Hash>] Model descriptors
   def list_models
     handle_errors do
       response = self.class.get('/v1/models',
@@ -157,25 +185,4 @@ class Prescient::Provider::OpenAI < Prescient::Base
     raise Prescient::Error, "Missing required options: #{missing_options.join(', ')}"
   end
 
-  private
-
-  def validate_response!(response, operation)
-    return if response.success?
-
-    case response.code
-    when 400
-      raise Prescient::Error, "Bad request for #{operation}: #{response.body}"
-    when 401
-      raise Prescient::AuthenticationError, "Authentication failed for #{operation}"
-    when 403
-      raise Prescient::AuthenticationError, "Forbidden access for #{operation}"
-    when 429
-      raise Prescient::RateLimitError, "Rate limit exceeded for #{operation}"
-    when 500..599
-      raise Prescient::Error, "OpenAI server error during #{operation}: #{response.body}"
-    else
-      raise Prescient::Error,
-            "OpenAI request failed for #{operation}: HTTP #{response.code} - #{response.message}"
-    end
-  end
 end

data/lib/prescient/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Prescient
-  VERSION = '0.1.0'
+  # Current Prescient gem version.
+  VERSION = '0.3.0'
 end

data/lib/prescient.rb

@@ -1,20 +1,8 @@
 # frozen_string_literal: true
 
 require_relative 'prescient/version'
-
-module Prescient
-  class Error < StandardError; end
-  class ConnectionError < Error; end
-  class AuthenticationError < Error; end
-  class RateLimitError < Error; end
-  class ModelNotAvailableError < Error; end
-  class InvalidResponseError < Error; end
-
-  module Provider
-    # Module for AI provider implementations
-  end
-end
-
+require_relative 'prescient/errors'
+require_relative 'prescient/pgvector'
 require_relative 'prescient/base'
 require_relative 'prescient/provider/ollama'
 require_relative 'prescient/provider/anthropic'
@@ -22,69 +10,205 @@ require_relative 'prescient/provider/openai'
 require_relative 'prescient/provider/huggingface'
 require_relative 'prescient/client'
 
+# Main Prescient module for AI provider abstraction
+#
+# Prescient provides a unified interface for working with multiple AI providers
+# including Ollama, OpenAI, Anthropic, and Hugging Face. 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)
 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 [Array<Symbol>] Built-in provider option keys removed from output
+    DEFAULT_SENSITIVE_KEYS = [:api_key, :password, :token, :secret].freeze
+
+    # @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 [Array<Symbol>] Additional keys removed from provider information
+    attr_reader :sensitive_keys
+
+    # @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 = []
+      @sensitive_keys = []
       @providers = {}
+      @provider_instances = {} # : Hash[Symbol, untyped]
     end
 
+    # Configure additional keys to remove from provider information.
+    # Built-in sensitive keys are always sanitized.
+    #
+    # @param keys [Array<Symbol, String>] Additional sensitive option keys
+    # @return [Array<Symbol>] Normalized additional keys
+    def sensitive_keys=(keys)
+      @sensitive_keys = Array(keys).map(&:to_sym).uniq
+    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.1-mini')
     def add_provider(name, provider_class, **options)
-      @providers[name.to_sym] = {
+      provider_name = name.to_sym
+      @providers[provider_name] = {
         class:   provider_class,
         options: options,
       }
+      @provider_instances.delete(provider_name)
     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]
+      provider_name = name.to_sym
+      provider_config = @providers[provider_name]
       return nil unless provider_config
 
-      provider_config[:class].new(**provider_config[:options])
+      provider_options = provider_config[:options] # : Hash[Symbol, untyped]
+      @provider_instances[provider_name] ||= provider_config[:class].new(**provider_options)
+    end
+
+    # Get list of providers that currently pass {Prescient::Base#available?}.
+    #
+    # Providers are included when their health check reports `reachable: true`,
+    # or, for legacy adapters, `status == "healthy"`.
+    #
+    # @return [Array<Symbol>] List of reachable provider names
+    def available_providers
+      @providers.keys.select do |name|
+        provider(name)&.available?
+      rescue StandardError
+        false
+      end
+    end
+  end
+
+  class << self
+    private
+
+    def configure_default_providers(config, env)
+      config.add_provider(:ollama,
+                          Prescient::Provider::Ollama,
+                          url:             env.fetch('OLLAMA_URL', 'http://localhost:11434'),
+                          embedding_model: env.fetch('OLLAMA_EMBEDDING_MODEL', 'nomic-embed-text'),
+                          chat_model:      env.fetch('OLLAMA_CHAT_MODEL', 'llama3.2:3b'))
+      if env['OPENAI_API_KEY']
+        config.add_provider(
+          :openai,
+          Prescient::Provider::OpenAI,
+          api_key:         env['OPENAI_API_KEY'],
+          embedding_model: env.fetch('OPENAI_EMBEDDING_MODEL', 'text-embedding-3-small'),
+          chat_model:      env.fetch('OPENAI_CHAT_MODEL', 'gpt-4.1-mini'),
+        )
+      end
+      if env['ANTHROPIC_API_KEY']
+        config.add_provider(
+          :anthropic,
+          Prescient::Provider::Anthropic,
+          api_key: env['ANTHROPIC_API_KEY'],
+          model:   env.fetch('ANTHROPIC_MODEL', 'claude-sonnet-4-20250514'),
+        )
+      end
+
+      return unless env['HUGGINGFACE_API_KEY']
+
+      config.add_provider(
+        :huggingface,
+        Prescient::Provider::HuggingFace,
+        api_key:         env['HUGGINGFACE_API_KEY'],
+        embedding_model: env.fetch(
+          'HUGGINGFACE_EMBEDDING_MODEL',
+          'sentence-transformers/all-MiniLM-L6-v2',
+        ),
+        chat_model:      env.fetch(
+          'HUGGINGFACE_CHAT_MODEL',
+          'google/gemma-2-2b-it',
+        ),
+      )
     end
   end
 
   # Default configuration
   configure do |config|
-    config.add_provider(:ollama, Prescient::Provider::Ollama,
-                        url:             ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
-                        embedding_model: ENV.fetch('OLLAMA_EMBEDDING_MODEL', 'nomic-embed-text'),
-                        chat_model:      ENV.fetch('OLLAMA_CHAT_MODEL', 'llama3.1:8b'))
-
-    config.add_provider(:anthropic, Prescient::Provider::Anthropic,
-                        api_key: ENV.fetch('ANTHROPIC_API_KEY', nil),
-                        model:   ENV.fetch('ANTHROPIC_MODEL', 'claude-3-haiku-20240307'))
-
-    config.add_provider(:openai, Prescient::Provider::OpenAI,
-                        api_key:         ENV.fetch('OPENAI_API_KEY', nil),
-                        embedding_model: ENV.fetch('OPENAI_EMBEDDING_MODEL', 'text-embedding-3-small'),
-                        chat_model:      ENV.fetch('OPENAI_CHAT_MODEL', 'gpt-3.5-turbo'))
-
-    config.add_provider(:huggingface, Prescient::Provider::HuggingFace,
-                        api_key:         ENV.fetch('HUGGINGFACE_API_KEY', nil),
-                        embedding_model: ENV.fetch('HUGGINGFACE_EMBEDDING_MODEL', 'sentence-transformers/all-MiniLM-L6-v2'),
-                        chat_model:      ENV.fetch('HUGGINGFACE_CHAT_MODEL', 'microsoft/DialoGPT-medium'))
+    configure_default_providers(config, ENV)
   end
 end

data/scripts/setup-ollama-models.sh

@@ -5,7 +5,7 @@ set -e
 
 OLLAMA_URL=${OLLAMA_URL:-"http://localhost:11434"}
 EMBEDDING_MODEL=${OLLAMA_EMBEDDING_MODEL:-"nomic-embed-text"}
-CHAT_MODEL=${OLLAMA_CHAT_MODEL:-"llama3.1:8b"}
+CHAT_MODEL=${OLLAMA_CHAT_MODEL:-"llama3.2:3b"}
 
 echo "🚀 Setting up Ollama models for Prescient gem..."
 echo "Ollama URL: $OLLAMA_URL"
@@ -74,4 +74,4 @@ main() {
     echo "   OLLAMA_URL=$OLLAMA_URL ruby examples/custom_contexts.rb"
 }
 
-main "$@"
+main "$@"