prescient 0.0.0 → 0.2.0

data/lib/prescient/client.rb

@@ -0,0 +1,211 @@
+# 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
+
+    # 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)
+      if @enable_fallback
+        with_fallback_handling(:generate_embedding, text, **options)
+      else
+        with_error_handling do
+          @provider.generate_embedding(text, **options)
+        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)
+      if @enable_fallback
+        with_fallback_handling(:generate_response, prompt, context_items, **options)
+      else
+        with_error_handling do
+          @provider.generate_response(prompt, context_items, **options)
+        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,
+        class:     @provider.class.name.split('::').last,
+        available: available?,
+        options:   sanitize_options(@provider.options),
+      }
+    end
+
+    def method_missing(method_name, ...)
+      @provider.respond_to?(method_name) ? @provider.send(method_name, ...) : super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @provider.respond_to?(method_name, include_private) || super
+    end
+
+    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) }
+    end
+
+    def with_error_handling
+      retries = 0
+      begin
+        yield
+      rescue Prescient::RateLimitError => e
+        raise e unless retries < Prescient.configuration.retry_attempts
+
+        retries += 1
+        sleep(Prescient.configuration.retry_delay * retries)
+        retry
+      rescue Prescient::ConnectionError => e
+        raise e unless retries < Prescient.configuration.retry_attempts
+
+        retries += 1
+        sleep(Prescient.configuration.retry_delay)
+        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, enable_fallback: true)
+    Client.new(provider_name, enable_fallback: enable_fallback)
+  end
+
+  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, 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, enable_fallback: false).health_check
+  end
+end

data/lib/prescient/provider/anthropic.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'httparty'
+
+class Prescient::Provider::Anthropic < Prescient::Base
+  include HTTParty
+
+  base_uri 'https://api.anthropic.com'
+
+  def initialize(**options)
+    super
+    self.class.default_timeout(@options[:timeout] || 60)
+  end
+
+  def generate_embedding(_text, **_options)
+    # Anthropic doesn't provide embedding API, raise error
+    raise Prescient::Error,
+          'Anthropic provider does not support embeddings. Use OpenAI or HuggingFace for embeddings.'
+  end
+
+  def generate_response(prompt, context_items = [], **options)
+    handle_errors do
+      formatted_prompt = build_prompt(prompt, context_items)
+
+      response = self.class.post('/v1/messages',
+                                 headers: {
+                                   'Content-Type'      => 'application/json',
+                                   'x-api-key'         => @options[:api_key],
+                                   'anthropic-version' => '2023-06-01',
+                                 },
+                                 body:    {
+                                   model:       @options[:model],
+                                   max_tokens:  options[:max_tokens] || 2000,
+                                   temperature: options[:temperature] || 0.7,
+                                   messages:    [
+                                     {
+                                       role:    'user',
+                                       content: formatted_prompt,
+                                     },
+                                   ],
+                                 }.to_json)
+
+      validate_response!(response, 'text generation')
+
+      content = response.parsed_response.dig('content', 0, 'text')
+      raise Prescient::InvalidResponseError, 'No response generated' unless content
+
+      {
+        response:        content.strip,
+        model:           @options[:model],
+        provider:        'anthropic',
+        processing_time: nil,
+        metadata:        {
+          usage: response.parsed_response['usage'],
+        },
+      }
+    end
+  end
+
+  def health_check
+    handle_errors do
+      # Test with a simple message
+      response = self.class.post('/v1/messages',
+                                 headers: {
+                                   'Content-Type'      => 'application/json',
+                                   'x-api-key'         => @options[:api_key],
+                                   'anthropic-version' => '2023-06-01',
+                                 },
+                                 body:    {
+                                   model:      @options[:model],
+                                   max_tokens: 10,
+                                   messages:   [
+                                     {
+                                       role:    'user',
+                                       content: 'Test',
+                                     },
+                                   ],
+                                 }.to_json)
+
+      if response.success?
+        {
+          status:   'healthy',
+          provider: 'anthropic',
+          model:    @options[:model],
+          ready:    true,
+        }
+      else
+        {
+          status:   'unhealthy',
+          provider: 'anthropic',
+          error:    "HTTP #{response.code}",
+          message:  response.message,
+        }
+      end
+    end
+  rescue Prescient::ConnectionError => e
+    {
+      status:   'unavailable',
+      provider: 'anthropic',
+      error:    e.class.name,
+      message:  e.message,
+    }
+  end
+
+  def list_models
+    # Anthropic doesn't provide a models list API
+    [
+      { name: 'claude-3-haiku-20240307', type: 'text' },
+      { name: 'claude-3-sonnet-20240229', type: 'text' },
+      { name: 'claude-3-opus-20240229', type: 'text' },
+    ]
+  end
+
+  protected
+
+  def validate_configuration!
+    required_options = [:api_key, :model]
+    missing_options = required_options.select { |opt| @options[opt].nil? }
+
+    return unless missing_options.any?
+
+    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, "Anthropic server error during #{operation}: #{response.body}"
+    else
+      raise Prescient::Error,
+            "Anthropic request failed for #{operation}: HTTP #{response.code} - #{response.message}"
+    end
+  end
+end

data/lib/prescient/provider/huggingface.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'httparty'
+
+class Prescient::Provider::HuggingFace < Prescient::Base
+  include HTTParty
+
+  base_uri 'https://api-inference.huggingface.co'
+
+  EMBEDDING_DIMENSIONS = {
+    'sentence-transformers/all-MiniLM-L6-v2'     => 384,
+    'sentence-transformers/all-mpnet-base-v2'    => 768,
+    'sentence-transformers/all-roberta-large-v1' => 1024,
+  }.freeze
+
+  def initialize(**options)
+    super
+    self.class.default_timeout(@options[:timeout] || 60)
+  end
+
+  def generate_embedding(text, **_options)
+    handle_errors do
+      clean_text_input = clean_text(text)
+
+      response = self.class.post("/pipeline/feature-extraction/#{@options[:embedding_model]}",
+                                 headers: {
+                                   'Content-Type'  => 'application/json',
+                                   'Authorization' => "Bearer #{@options[:api_key]}",
+                                 },
+                                 body:    {
+                                   inputs:  clean_text_input,
+                                   options: {
+                                     wait_for_model: true,
+                                   },
+                                 }.to_json)
+
+      validate_response!(response, 'embedding generation')
+
+      # HuggingFace returns embeddings as nested arrays, get the first one
+      embedding_data = response.parsed_response
+      embedding_data = embedding_data.first if embedding_data.is_a?(Array) && embedding_data.first.is_a?(Array)
+
+      raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding_data.is_a?(Array)
+
+      expected_dimensions = EMBEDDING_DIMENSIONS[@options[:embedding_model]] || 384
+      normalize_embedding(embedding_data, expected_dimensions)
+    end
+  end
+
+  def generate_response(prompt, context_items = [], **options)
+    handle_errors do
+      formatted_prompt = build_prompt(prompt, context_items)
+
+      response = self.class.post("/models/#{@options[:chat_model]}",
+                                 headers: {
+                                   'Content-Type'  => 'application/json',
+                                   'Authorization' => "Bearer #{@options[:api_key]}",
+                                 },
+                                 body:    {
+                                   inputs:     formatted_prompt,
+                                   parameters: {
+                                     max_new_tokens:   options[:max_tokens] || 2000,
+                                     temperature:      options[:temperature] || 0.7,
+                                     top_p:            options[:top_p] || 0.9,
+                                     return_full_text: false,
+                                   },
+                                   options:    {
+                                     wait_for_model: true,
+                                   },
+                                 }.to_json)
+
+      validate_response!(response, 'text generation')
+
+      # HuggingFace returns different formats depending on the model
+      generated_text = nil
+      parsed_response = response.parsed_response
+
+      if parsed_response.is_a?(Array) && parsed_response.first.is_a?(Hash)
+        generated_text = parsed_response.first['generated_text']
+      elsif parsed_response.is_a?(Hash)
+        generated_text = parsed_response['generated_text'] || parsed_response['text']
+      end
+
+      raise Prescient::InvalidResponseError, 'No response generated' unless generated_text
+
+      {
+        response:        generated_text.strip,
+        model:           @options[:chat_model],
+        provider:        'huggingface',
+        processing_time: nil,
+        metadata:        {},
+      }
+    end
+  end
+
+  def health_check
+    handle_errors do
+      # Test embedding model
+      embedding_response = self.class.post("/pipeline/feature-extraction/#{@options[:embedding_model]}",
+                                           headers: {
+                                             'Authorization' => "Bearer #{@options[:api_key]}",
+                                           },
+                                           body:    { inputs: 'test' }.to_json)
+
+      # Test chat model
+      chat_response = self.class.post("/models/#{@options[:chat_model]}",
+                                      headers: {
+                                        'Authorization' => "Bearer #{@options[:api_key]}",
+                                      },
+                                      body:    {
+                                        inputs:     'test',
+                                        parameters: { max_new_tokens: 5 },
+                                      }.to_json)
+
+      embedding_healthy = embedding_response.success?
+      chat_healthy = chat_response.success?
+
+      {
+        status:          embedding_healthy && chat_healthy ? 'healthy' : 'partial',
+        provider:        'huggingface',
+        embedding_model: {
+          name:      @options[:embedding_model],
+          available: embedding_healthy,
+        },
+        chat_model:      {
+          name:      @options[:chat_model],
+          available: chat_healthy,
+        },
+        ready:           embedding_healthy && chat_healthy,
+      }
+    end
+  rescue Prescient::ConnectionError => e
+    {
+      status:   'unavailable',
+      provider: 'huggingface',
+      error:    e.class.name,
+      message:  e.message,
+    }
+  end
+
+  def list_models
+    # HuggingFace doesn't provide a simple API to list all models
+    # Return the configured models
+    [
+      {
+        name:       @options[:embedding_model],
+        type:       'embedding',
+        dimensions: EMBEDDING_DIMENSIONS[@options[:embedding_model]],
+      },
+      {
+        name: @options[:chat_model],
+        type: 'text-generation',
+      },
+    ]
+  end
+
+  protected
+
+  def validate_configuration!
+    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(', ')}"
+  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 503
+      # HuggingFace model loading
+      error_body = begin
+        response.parsed_response
+      rescue StandardError
+        response.body
+      end
+      if error_body.is_a?(Hash) && error_body['error']&.include?('loading')
+        raise Prescient::Error, 'Model is loading, please try again later'
+      end
+
+      raise Prescient::Error, "HuggingFace service unavailable for #{operation}"
+
+    when 500..599
+      raise Prescient::Error, "HuggingFace server error during #{operation}: #{response.body}"
+    else
+      raise Prescient::Error,
+            "HuggingFace request failed for #{operation}: HTTP #{response.code} - #{response.message}"
+    end
+  end
+end