prescient 0.2.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.2.0'
+  # Current Prescient gem version.
+  VERSION = '0.3.0'
 end

data/lib/prescient.rb

@@ -1,11 +1,19 @@
 # frozen_string_literal: true
 
 require_relative 'prescient/version'
+require_relative 'prescient/errors'
+require_relative 'prescient/pgvector'
+require_relative 'prescient/base'
+require_relative 'prescient/provider/ollama'
+require_relative 'prescient/provider/anthropic'
+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 HuggingFace. It supports both
+# including Ollama, OpenAI, Anthropic, and Hugging Face. It supports both
 # embedding generation and text completion with configurable context handling.
 #
 # @example Basic usage
@@ -20,44 +28,6 @@ require_relative 'prescient/version'
 # @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
-end
-
-require_relative 'prescient/base'
-require_relative 'prescient/provider/ollama'
-require_relative 'prescient/provider/anthropic'
-require_relative 'prescient/provider/openai'
-require_relative 'prescient/provider/huggingface'
-require_relative 'prescient/client'
-
 module Prescient
   # Configure Prescient with custom settings and providers
   #
@@ -95,6 +65,9 @@ module Prescient
   # 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
 
@@ -110,6 +83,9 @@ module Prescient
     # @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
 
@@ -120,7 +96,18 @@ module Prescient
       @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
@@ -137,12 +124,14 @@ module Prescient
     # @example Add OpenAI provider
     #   config.add_provider(:openai, Prescient::Provider::OpenAI,
     #                       api_key: 'sk-...',
-    #                       chat_model: 'gpt-4')
+    #                       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
@@ -150,15 +139,20 @@ module Prescient
     # @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 available providers (those that are configured and healthy)
+    # 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 available provider names
+    # @return [Array<Symbol>] List of reachable provider names
     def available_providers
       @providers.keys.select do |name|
         provider(name)&.available?
@@ -168,25 +162,53 @@ module Prescient
     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 "$@"