prescient 0.2.0 → 0.4.0

data/lib/prescient/cli.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'optparse'
+
+# Command-line interface for common Prescient operations.
+class Prescient::CLI
+  # Supported output formats.
+  # @return [Array<String>] Output format names
+  FORMATS = ['text', 'json'].freeze
+
+  # Raised when command-line arguments are invalid or incomplete.
+  class UsageError < StandardError; end
+
+  # Run the CLI and return a process exit status.
+  #
+  # @param arguments [Array<String>] Command-line arguments
+  # @param input [IO] Input stream used for stdin prompts
+  # @param output [IO] Output stream for command results
+  # @param errors [IO] Output stream for diagnostics
+  # @return [Integer] Process exit status
+  def self.run(arguments, input: $stdin, output: $stdout, errors: $stderr)
+    new(arguments, input:, output:, errors:).run
+  rescue UsageError, OptionParser::ParseError => e
+    errors.puts "prescient: #{e.message}"
+    2
+  rescue Prescient::Error => e
+    errors.puts "prescient: #{e.message}"
+    1
+  end
+
+  # Initialize a CLI runner with injectable streams.
+  #
+  # @param arguments [Array<String>] Command-line arguments
+  # @param input [IO] Input stream used for stdin prompts
+  # @param output [IO] Output stream for command results
+  # @param errors [IO] Output stream for diagnostics
+  def initialize(arguments, input:, output:, errors:)
+    @arguments = arguments.dup
+    @input = input
+    @output = output
+    @errors = errors
+  end
+
+  def run
+    command = @arguments.shift
+    return print_help(2) unless command
+
+    case command
+    when 'providers' then providers
+    when 'health' then health
+    when 'generate' then generate
+    when 'embed' then embed
+    when 'config' then config
+    when 'help', '--help', '-h' then print_help(0)
+    else
+      raise UsageError, "unknown command #{command.inspect}; run 'prescient help'"
+    end
+  end
+
+  private
+
+  def providers
+    options = parse_options('List configured providers')
+    return options if options.is_a?(Integer)
+
+    provider_list = Prescient.configuration.providers.map { |name, registration|
+      { name: name.to_s, class: registration[:class].name }
+    }
+
+    if options[:format] == 'json'
+      print_json(providers: provider_list)
+    else
+      provider_list.each { |provider| @output.puts "#{provider[:name]}\t#{provider[:class]}" }
+    end
+    0
+  end
+
+  def health
+    options = parse_options('Check provider health')
+    return options if options.is_a?(Integer)
+
+    names = options[:provider] ? [options[:provider].to_sym] : Prescient.configuration.providers.keys
+    raise UsageError, 'no providers are configured' if names.empty?
+
+    results = names.to_h { |name| [name.to_s, Prescient.health_check(provider: name)] }
+    output_health(results, options[:format])
+    results.values.all? { |result| result[:reachable] != false } ? 0 : 1
+  end
+
+  def generate
+    options = parse_options('Generate a text response', fallback: true)
+    return options if options.is_a?(Integer)
+
+    prompt = read_text(options[:arguments], 'prompt')
+    client = client_for(options)
+    response = client.generate_response(prompt, **model_options(options))
+
+    options[:format] == 'json' ? print_json(response) : @output.puts(response[:response])
+    0
+  end
+
+  def embed
+    options = parse_options('Generate an embedding', fallback: true)
+    return options if options.is_a?(Integer)
+
+    text = read_text(options[:arguments], 'text')
+    client = client_for(options)
+    embedding = client.generate_embedding(text, **model_options(options))
+
+    if options[:format] == 'json'
+      print_json(embedding: embedding, dimensions: embedding.length, provider: client.provider_name.to_s)
+    else
+      @output.puts JSON.generate(embedding)
+    end
+    0
+  end
+
+  def config
+    subcommand = @arguments.shift
+    raise UsageError, "unknown config command #{subcommand.inspect}" unless subcommand == 'validate'
+
+    options = parse_options('Validate the current configuration')
+    return options if options.is_a?(Integer)
+
+    validate_configuration
+    if options[:format] == 'json'
+      print_json(valid: true, providers: Prescient.configuration.providers.keys.map(&:to_s))
+    else
+      @output.puts 'configuration valid'
+    end
+    0
+  end
+
+  def validate_configuration
+    configuration = Prescient.configuration
+    unless configuration.provider(configuration.default_provider)
+      raise Prescient::Error, 'default provider is not configured'
+    end
+
+    configuration.providers.each_key { |name| configuration.provider(name) }
+  end
+
+  def parse_options(description, fallback: false)
+    options = { format: 'text', fallback: fallback }
+    parser = OptionParser.new do |parser|
+      parser.banner = "Usage: prescient #{@arguments.first || 'command'} [options]"
+      parser.separator description
+      add_common_options(parser, options)
+      parser.on('--no-fallback', 'Disable provider fallback') { options[:fallback] = false } if fallback
+      parser.on('-h', '--help', 'Show command help') do
+        @output.puts parser
+        throw :help_shown, 0
+      end
+    end
+
+    result = catch(:help_shown) { parse_arguments(parser) }
+    return result unless result.nil?
+
+    options[:arguments] = @arguments
+    options
+  end
+
+  def add_common_options(parser, options)
+    parser.on('--format FORMAT', FORMATS, "Output format (#{FORMATS.join(', ')})") do |value|
+      options[:format] = value
+    end
+    parser.on('--provider NAME', 'Use a specific provider') do |value|
+      options[:provider] = value
+    end
+    add_model_options(parser, options)
+    add_credential_options(parser, options)
+  end
+
+  # Parse command arguments and return nil when parsing completes.
+  #
+  # @param parser [OptionParser] Configured command option parser
+  # @return [nil]
+  def parse_arguments(parser)
+    parser.parse!(@arguments)
+    nil
+  end
+
+  def model_options(options)
+    options[:model] ? { model: options[:model] } : {}
+  end
+
+  def client_for(options)
+    validate_override_options(options)
+    Prescient.client(
+      options[:provider]&.to_sym,
+      enable_fallback:  options[:fallback],
+      provider_options: provider_options(options),
+    )
+  rescue KeyError => e
+    raise UsageError, "environment variable not set: #{e.key}"
+  end
+
+  def add_model_options(parser, options)
+    parser.on('--model NAME', 'Override the configured model') do |value|
+      options[:model] = value
+    end
+    parser.on('--embedding-model NAME', 'Override the embedding model') do |value|
+      options[:embedding_model] = value
+    end
+    parser.on('--chat-model NAME', 'Override the chat model') do |value|
+      options[:chat_model] = value
+    end
+  end
+
+  def add_credential_options(parser, options)
+    parser.on('--api-key KEY', 'Use an API key for this operation') do |value|
+      options[:api_key] = value
+    end
+    parser.on('--api-key-env NAME', 'Read the API key from this environment variable') do |value|
+      options[:api_key_env] = value
+    end
+  end
+
+  def validate_override_options(options)
+    if options[:model] && (options[:embedding_model] || options[:chat_model])
+      raise UsageError, '--model cannot be combined with --embedding-model or --chat-model'
+    end
+    return unless options[:api_key] && options[:api_key_env]
+
+    raise UsageError, '--api-key cannot be combined with --api-key-env'
+  end
+
+  def provider_options(options)
+    {
+      api_key:         api_key_override(options),
+      embedding_model: options[:embedding_model],
+      chat_model:      options[:chat_model],
+    }.compact
+  end
+
+  def api_key_override(options)
+    return options[:api_key] if options[:api_key]
+    return ENV.fetch(options[:api_key_env]) if options[:api_key_env]
+
+    nil
+  end
+
+  def output_health(results, format)
+    if format == 'json'
+      print_json(results)
+    else
+      results.each do |name, result|
+        @output.puts '%<name>-12s %<status>s' % { name: name, status: result[:status] || 'unknown' }
+      end
+    end
+  end
+
+  def read_text(arguments, label)
+    return arguments.join(' ') unless arguments.empty?
+    return @input.read unless @input.tty?
+
+    raise UsageError, "missing #{label}; provide it as an argument or through stdin"
+  end
+
+  def print_json(value)
+    @output.puts JSON.generate(value)
+  end
+
+  def print_help(status)
+    @output.puts <<~HELP
+      Usage: prescient COMMAND [options]
+
+      Commands:
+        providers       List configured providers
+        health          Check provider health
+        generate TEXT   Generate a text response
+        embed TEXT      Generate an embedding
+        config validate Validate the current configuration
+
+      Options:
+        --provider NAME          Select a provider
+        --model NAME             Override the selected operation's model
+        --chat-model NAME        Override the chat model
+        --embedding-model NAME   Override the embedding model
+        --api-key KEY            Use an API key for the operation
+        --api-key-env NAME       Read the API key from an environment variable
+        --format FORMAT          Use text or json output
+    HELP
+    status
+  end
+end

data/lib/prescient/client.rb

@@ -16,26 +16,25 @@ module Prescient
   #   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
+    # @return [Prescient::Base] The underlying provider instance
     attr_reader :provider
 
     # 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
+    # @param provider_options [Hash] Temporary options for the selected provider
     # @raise [Prescient::Error] If the specified provider is not configured
-    def initialize(provider_name = nil, enable_fallback: true)
+    def initialize(provider_name = nil, enable_fallback: true, provider_options: {})
       @provider_name = provider_name || Prescient.configuration.default_provider
-      @provider = Prescient.configuration.provider(@provider_name)
+      @provider = provider_with_options(@provider_name, provider_options)
       @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
@@ -84,14 +83,14 @@ module Prescient
 
     # Check the health status of the provider
     #
-    # @return [Hash] Health status information
+    # @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 provider is healthy and available
+    # @return [Boolean] true if the provider currently passes its availability check
     def available?
       @provider.available?
     end
@@ -101,7 +100,8 @@ module Prescient
     # Returns details about the provider including its availability
     # and configuration options (with sensitive data removed).
     #
-    # @return [Hash] Provider information including :name, :class, :available, :options
+    # @return [Hash] Provider information including :name, :class, :available,
+    #   and recursively sanitized :options
     def provider_info
       {
         name:      @provider_name,
@@ -111,20 +111,35 @@ module Prescient
       }
     end
 
-    def method_missing(method_name, ...)
-      @provider.respond_to?(method_name) ? @provider.send(method_name, ...) : super
-    end
+    private
+
+    def sanitize_options(options)
+      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)
 
-    def respond_to_missing?(method_name, include_private = false)
-      @provider.respond_to?(method_name, include_private) || super
+          sanitized[key] = sanitize_options(value)
+        end
+        sanitized
+      when Array
+        options.map { |value| sanitize_options(value) }
+      else
+        options
+      end
     end
 
-    private
+    def provider_with_options(provider_name, provider_options)
+      return Prescient.configuration.provider(provider_name) if provider_options.empty?
 
-    # 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) }
+      registration = Prescient.configuration.providers[provider_name.to_sym]
+      return unless registration
+
+      registration_options = registration[:options] # : Hash[Symbol, untyped]
+      registration[:class].new(**registration_options, **provider_options)
     end
 
     def with_error_handling
@@ -150,24 +165,17 @@ module Prescient
       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
+        provider = provider_for(provider_name, index)
         next unless provider
 
-        # Check if provider is available before trying
-        next unless provider.available?
-
-        # Use retry logic for each 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
-        # Log the error and continue to next provider
         next
       end
 
@@ -175,36 +183,74 @@ module Prescient
       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
-      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
+      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, enable_fallback: true)
-    Client.new(provider_name, enable_fallback: enable_fallback)
+  #
+  # @param provider_name [Symbol, nil] Provider to use, or the configured default
+  # @param enable_fallback [Boolean] Whether provider fallback is enabled
+  # @param provider_options [Hash] Temporary options for the selected provider
+  # @return [Client] A configured client instance
+  def self.client(provider_name = nil, enable_fallback: true, provider_options: {})
+    Client.new(provider_name, enable_fallback: enable_fallback, provider_options: provider_options)
   end
 
+  # 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
 
+  # 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, enable_fallback: false).health_check
   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