prescient 0.4.0 → 0.5.0

data/lib/prescient/provider/gemini.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'httparty'
+
+# Google Gemini API provider adapter.
+class Prescient::Provider::Gemini < Prescient::Base
+  include HTTParty
+
+  base_uri 'https://generativelanguage.googleapis.com'
+
+  def initialize(**options)
+    super
+    @provider_name = 'Google Gemini'
+    self.class.default_timeout(@options[:timeout] || 60)
+  end
+
+  # Generate an embedding through Gemini's embedContent endpoint.
+  # @param text [String] Text to embed
+  # @return [Array<Float>] Embedding vector
+  def generate_embedding(text, **options)
+    handle_errors do
+      embedding_model = options[:model] || @options[:embedding_model]
+      response = self.class.post(
+        model_endpoint(embedding_model, 'embedContent'),
+        headers: api_headers,
+        body:    {
+          content: { parts: [{ text: clean_text(text) }] },
+        }.to_json,
+      )
+
+      validate_response!(response, 'embedding generation')
+
+      embedding = response.parsed_response.dig('embedding', 'values')
+      raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding.is_a?(Array)
+
+      expected_dimensions = @options[:embedding_dimensions]
+      expected_dimensions ? validate_embedding_dimensions(embedding, expected_dimensions) : embedding
+    end
+  end
+
+  # Generate a response through Gemini's generateContent 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
+      model = options[:model] || @options[:chat_model]
+      response = self.class.post(
+        model_endpoint(model, 'generateContent'),
+        headers: api_headers,
+        body:    {
+          contents:         [{ role: 'user', parts: [{ text: build_prompt(prompt, context_items) }] }],
+          generationConfig: {
+            maxOutputTokens: options[:max_tokens] || 2000,
+            temperature:     options[:temperature] || 0.7,
+            topP:            options[:top_p] || 0.9,
+          },
+        }.to_json,
+      )
+
+      validate_response!(response, 'text generation')
+
+      parsed_response = response.parsed_response
+      parts = parsed_response.dig('candidates', 0, 'content', 'parts')
+      content = Array(parts).filter_map { |part| part['text'] }.join
+      raise Prescient::InvalidResponseError, 'No response generated' if content.nil? || content.empty?
+
+      {
+        response:        content.strip,
+        model:           model,
+        provider:        'gemini',
+        processing_time: nil,
+        metadata:        {
+          usage:         parsed_response['usageMetadata'],
+          finish_reason: parsed_response.dig('candidates', 0, 'finishReason'),
+        },
+      }
+    end
+  end
+
+  # Check whether the configured Gemini models are available.
+  # @return [Hash] Provider health information
+  def health_check
+    handle_errors do
+      response = self.class.get('/v1beta/models', headers: api_headers)
+
+      if response.success?
+        models = response.parsed_response['models'] || []
+        embedding_model = find_model(models, @options[:embedding_model], 'embedContent')
+        chat_model = find_model(models, @options[:chat_model], 'generateContent')
+
+        {
+          status:           'healthy',
+          provider:         'gemini',
+          reachable:        true,
+          models_available: models.map { |model| model['name'].to_s.delete_prefix('models/') },
+          embedding_model:  { name: @options[:embedding_model], available: embedding_model },
+          chat_model:       { name: @options[:chat_model], available: chat_model },
+          ready:            embedding_model && chat_model,
+        }
+      else
+        {
+          status:    'unhealthy',
+          provider:  'gemini',
+          reachable: true,
+          error:     "HTTP #{response.code}",
+          message:   response.message,
+          ready:     false,
+        }
+      end
+    end
+  rescue Prescient::Error => e
+    {
+      status:    'unavailable',
+      provider:  'gemini',
+      reachable: false,
+      error:     e.class.name,
+      message:   e.message,
+      ready:     false,
+    }
+  end
+
+  # List models available to the configured Gemini API key.
+  # @return [Array<Hash>] Model descriptors
+  def list_models
+    handle_errors do
+      response = self.class.get('/v1beta/models', headers: api_headers)
+      validate_response!(response, 'model listing')
+
+      (response.parsed_response['models'] || []).map do |model|
+        {
+          name:                       model['name'].to_s.delete_prefix('models/'),
+          display_name:               model['displayName'],
+          supported_generation_modes: model['supportedGenerationMethods'],
+          input_token_limit:          model['inputTokenLimit'],
+          output_token_limit:         model['outputTokenLimit'],
+        }.compact
+      end
+    end
+  end
+
+  protected
+
+  def validate_configuration!
+    required_options = [:api_key, :embedding_model, :chat_model]
+    missing_options = required_options.select { |option| @options[option].nil? }
+
+    return unless missing_options.any?
+
+    raise Prescient::Error, "Missing required options: #{missing_options.join(', ')}"
+  end
+
+  private
+
+  def api_headers
+    {
+      'Content-Type'   => 'application/json',
+      'x-goog-api-key' => @options[:api_key],
+    }
+  end
+
+  def model_endpoint(model, operation)
+    model_name = model.to_s.delete_prefix('models/')
+    "/v1beta/models/#{model_name}:#{operation}"
+  end
+
+  def find_model(models, model_name, operation)
+    models.any? do |model|
+      model['name'].to_s.delete_prefix('models/') == model_name &&
+        model.fetch('supportedGenerationMethods', []).include?(operation)
+    end
+  end
+end

data/lib/prescient/provider/huggingface.rb

@@ -29,6 +29,7 @@ class Prescient::Provider::HuggingFace < Prescient::Base
 
   def initialize(**options)
     super
+    @provider_name = 'Hugging Face'
     self.class.default_timeout(@options[:timeout] || 60)
   end
 

data/lib/prescient/provider/mistral.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'httparty'
+
+# Mistral AI API provider adapter.
+class Prescient::Provider::Mistral < Prescient::Base
+  include HTTParty
+
+  base_uri 'https://api.mistral.ai'
+
+  def initialize(**options)
+    super
+    self.class.default_timeout(@options[:timeout] || 60)
+  end
+
+  # Generate an embedding through Mistral's embeddings API.
+  # @param text [String] Text to embed
+  # @return [Array<Float>] Embedding vector
+  def generate_embedding(text, **options)
+    handle_errors do
+      embedding_model = options[:model] || @options[:embedding_model]
+      response = self.class.post(
+        '/v1/embeddings',
+        headers: api_headers,
+        body:    {
+          model: embedding_model,
+          input: clean_text(text),
+        }.to_json,
+      )
+
+      validate_response!(response, 'embedding generation')
+
+      embedding = response.parsed_response.dig('data', 0, 'embedding')
+      raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding.is_a?(Array)
+
+      expected_dimensions = @options[:embedding_dimensions]
+      expected_dimensions ? validate_embedding_dimensions(embedding, expected_dimensions) : embedding
+    end
+  end
+
+  # Generate a response through Mistral's 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
+      model = options[:model] || @options[:chat_model]
+      response = self.class.post(
+        '/v1/chat/completions',
+        headers: api_headers,
+        body:    {
+          model:       model,
+          messages:    [{ role: 'user', content: build_prompt(prompt, context_items) }],
+          max_tokens:  options[:max_tokens] || 2000,
+          temperature: options[:temperature] || 0.7,
+          top_p:       options[:top_p] || 0.9,
+        }.to_json,
+      )
+
+      validate_response!(response, 'text generation')
+
+      parsed_response = response.parsed_response
+      content = normalize_content(parsed_response.dig('choices', 0, 'message', 'content'))
+      raise Prescient::InvalidResponseError, 'No response generated' if content.nil? || content.empty?
+
+      {
+        response:        content.strip,
+        model:           model,
+        provider:        'mistral',
+        processing_time: nil,
+        metadata:        {
+          usage:         parsed_response['usage'],
+          finish_reason: parsed_response.dig('choices', 0, 'finish_reason'),
+        },
+      }
+    end
+  end
+
+  # Check whether the configured Mistral models are available.
+  # @return [Hash] Provider health information
+  def health_check
+    handle_errors do
+      response = self.class.get('/v1/models', headers: api_headers)
+
+      if response.success?
+        models = response.parsed_response['data'] || []
+        embedding_available = model_available?(models, @options[:embedding_model])
+        chat_available = model_available?(models, @options[:chat_model])
+
+        {
+          status:           'healthy',
+          provider:         'mistral',
+          reachable:        true,
+          models_available: models.map { |model| model['id'] },
+          embedding_model:  { name: @options[:embedding_model], available: embedding_available },
+          chat_model:       { name: @options[:chat_model], available: chat_available },
+          ready:            embedding_available && chat_available,
+        }
+      else
+        {
+          status:    'unhealthy',
+          provider:  'mistral',
+          reachable: true,
+          error:     "HTTP #{response.code}",
+          message:   response.message,
+          ready:     false,
+        }
+      end
+    end
+  rescue Prescient::Error => e
+    {
+      status:    'unavailable',
+      provider:  'mistral',
+      reachable: false,
+      error:     e.class.name,
+      message:   e.message,
+      ready:     false,
+    }
+  end
+
+  # List models available to the configured Mistral API key.
+  # @return [Array<Hash>] Model descriptors
+  def list_models
+    handle_errors do
+      response = self.class.get('/v1/models', headers: api_headers)
+      validate_response!(response, 'model listing')
+
+      (response.parsed_response['data'] || []).map do |model|
+        {
+          name:               model['id'],
+          object:             model['object'],
+          created:            model['created'],
+          owned_by:           model['owned_by'],
+          capabilities:       model['capabilities'],
+          max_context_length: model['max_context_length'],
+        }.compact
+      end
+    end
+  end
+
+  protected
+
+  def validate_configuration!
+    required_options = [:api_key, :embedding_model, :chat_model]
+    missing_options = required_options.select { |option| @options[option].nil? }
+
+    return unless missing_options.any?
+
+    raise Prescient::Error, "Missing required options: #{missing_options.join(', ')}"
+  end
+
+  private
+
+  def api_headers
+    {
+      'Content-Type'  => 'application/json',
+      'Authorization' => "Bearer #{@options[:api_key]}",
+    }
+  end
+
+  def model_available?(models, model_name)
+    models.any? { |model| model['id'] == model_name }
+  end
+
+  def normalize_content(content)
+    return content if content.is_a?(String)
+    return unless content.is_a?(Array)
+
+    content.filter_map { |part| part['text'] if part.is_a?(Hash) }.join
+  end
+end

data/lib/prescient/provider/openai.rb

@@ -17,6 +17,7 @@ class Prescient::Provider::OpenAI < Prescient::Base
 
   def initialize(**options)
     super
+    @provider_name = 'OpenAI'
     self.class.default_timeout(@options[:timeout] || 60)
   end
 
@@ -82,6 +83,8 @@ class Prescient::Provider::OpenAI < Prescient::Base
 
       validate_response!(response, 'text generation')
 
+      puts "response.parsed_response: #{response.parsed_response.inspect}"
+
       content = response.parsed_response.dig('choices', 0, 'message', 'content')
       raise Prescient::InvalidResponseError, 'No response generated' unless content
 

data/lib/prescient/provider/xai.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'httparty'
+
+# xAI API provider adapter.
+class Prescient::Provider::XAI < Prescient::Base
+  include HTTParty
+
+  base_uri 'https://api.x.ai'
+
+  def initialize(**options)
+    super
+    @provider_name = 'xAI'
+    self.class.default_timeout(@options[:timeout] || 60)
+  end
+
+  # xAI does not expose a standard embeddings API for this adapter.
+  # @raise [Prescient::Error] Always, because embeddings are unsupported
+  def generate_embedding(_text, **_options)
+    raise Prescient::Error, 'xAI provider does not support embeddings.'
+  end
+
+  # Generate a response through xAI's OpenAI-compatible chat 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
+      model = options[:model] || @options[:chat_model]
+      response = self.class.post(
+        '/v1/chat/completions',
+        headers: api_headers,
+        body:    {
+          model:       model,
+          messages:    [{ role: 'user', content: build_prompt(prompt, context_items) }],
+          max_tokens:  options[:max_tokens] || 2000,
+          temperature: options[:temperature] || 0.7,
+          top_p:       options[:top_p] || 0.9,
+        }.to_json,
+      )
+
+      validate_response!(response, 'text generation')
+
+      parsed_response = response.parsed_response
+      content = parsed_response.dig('choices', 0, 'message', 'content')
+      raise Prescient::InvalidResponseError, 'No response generated' unless content.is_a?(String) && !content.empty?
+
+      {
+        response:        content.strip,
+        model:           model,
+        provider:        'xai',
+        processing_time: nil,
+        metadata:        {
+          usage:         parsed_response['usage'],
+          finish_reason: parsed_response.dig('choices', 0, 'finish_reason'),
+        },
+      }
+    end
+  end
+
+  # Check whether the configured xAI model is available.
+  # @return [Hash] Provider health information
+  def health_check
+    handle_errors do
+      response = self.class.get('/v1/models', headers: api_headers)
+
+      if response.success?
+        models = response.parsed_response['data'] || []
+        model_available = models.any? { |model| model['id'] == @options[:chat_model] }
+
+        {
+          status:           'healthy',
+          provider:         'xai',
+          reachable:        true,
+          models_available: models.map { |model| model['id'] },
+          chat_model:       { name: @options[:chat_model], available: model_available },
+          ready:            model_available,
+        }
+      else
+        {
+          status:    'unhealthy',
+          provider:  'xai',
+          reachable: true,
+          error:     "HTTP #{response.code}",
+          message:   response.message,
+          ready:     false,
+        }
+      end
+    end
+  rescue Prescient::Error => e
+    {
+      status:    'unavailable',
+      provider:  'xai',
+      reachable: false,
+      error:     e.class.name,
+      message:   e.message,
+      ready:     false,
+    }
+  end
+
+  # List models available to the configured xAI API key.
+  # @return [Array<Hash>] Model descriptors
+  def list_models
+    handle_errors do
+      response = self.class.get('/v1/models', headers: api_headers)
+      validate_response!(response, 'model listing')
+
+      (response.parsed_response['data'] || []).map do |model|
+        {
+          name:           model['id'],
+          object:         model['object'],
+          created:        model['created'],
+          owned_by:       model['owned_by'],
+          context_length: model['context_length'],
+        }.compact
+      end
+    end
+  end
+
+  protected
+
+  def validate_configuration!
+    required_options = [:api_key, :chat_model]
+    missing_options = required_options.select { |option| @options[option].nil? }
+
+    return unless missing_options.any?
+
+    raise Prescient::Error, "Missing required options: #{missing_options.join(', ')}"
+  end
+
+  private
+
+  def api_headers
+    {
+      'Content-Type'  => 'application/json',
+      'Authorization' => "Bearer #{@options[:api_key]}",
+    }
+  end
+end

data/lib/prescient/version.rb

@@ -2,5 +2,5 @@
 
 module Prescient
   # Current Prescient gem version.
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/prescient.rb

@@ -8,6 +8,11 @@ require_relative 'prescient/provider/ollama'
 require_relative 'prescient/provider/anthropic'
 require_relative 'prescient/provider/openai'
 require_relative 'prescient/provider/huggingface'
+require_relative 'prescient/provider/gemini'
+require_relative 'prescient/provider/mistral'
+require_relative 'prescient/provider/deepseek'
+require_relative 'prescient/provider/xai'
+require_relative 'prescient/configuration_loader'
 require_relative 'prescient/client'
 require_relative 'prescient/cli'
 
@@ -61,6 +66,28 @@ module Prescient
     @_configuration = Configuration.new
   end
 
+  # Load configuration from a YAML file and replace the current configuration.
+  #
+  # The loaded configuration starts from the current environment defaults,
+  # then applies the YAML file, environment-variable references, and any
+  # optional overrides.
+  #
+  # @param path [String, nil] YAML configuration file path
+  # @param env [Hash] Environment variables used while loading configuration
+  # @return [Configuration] The loaded configuration
+  def self.load_configuration(path = nil, env: ENV)
+    effective_path = path || env['PRESCIENT_CONFIG']
+    configuration = if effective_path
+                      ConfigurationLoader.load_file(effective_path, env:)
+                    else
+                      Configuration.new.tap do |config|
+                        configure_default_providers(config, env)
+                      end
+                    end
+
+    @_configuration = configuration
+  end
+
   # Configuration class for managing Prescient settings and providers
   #
   # Handles global settings like timeouts and retry behavior, as well as
@@ -167,29 +194,62 @@ module Prescient
     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
+      configure_ollama(config, env)
+      configure_openai(config, env)
+      configure_anthropic(config, env)
+      configure_gemini(config, env)
+      configure_mistral(config, env)
+      configure_deepseek(config, env)
+      configure_xai(config, env)
+      configure_huggingface(config, env)
+    end
+
+    def configure_ollama(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'),
+      )
+    end
+
+    def configure_openai(config, env)
+      return unless 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
+
+    def configure_anthropic(config, env)
+      return unless 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
+
+    def configure_gemini(config, env)
+      return unless env['GEMINI_API_KEY']
+
+      config.add_provider(
+        :gemini,
+        Prescient::Provider::Gemini,
+        api_key:         env['GEMINI_API_KEY'],
+        embedding_model: env.fetch('GEMINI_EMBEDDING_MODEL', 'gemini-embedding-001'),
+        chat_model:      env.fetch('GEMINI_CHAT_MODEL', 'gemini-2.5-flash'),
+      )
+    end
 
+    def configure_huggingface(config, env)
       return unless env['HUGGINGFACE_API_KEY']
 
       config.add_provider(
@@ -206,6 +266,40 @@ module Prescient
         ),
       )
     end
+
+    def configure_deepseek(config, env)
+      return unless env['DEEPSEEK_API_KEY']
+
+      config.add_provider(
+        :deepseek,
+        Prescient::Provider::DeepSeek,
+        api_key:    env['DEEPSEEK_API_KEY'],
+        chat_model: env.fetch('DEEPSEEK_CHAT_MODEL', 'deepseek-v4-flash'),
+      )
+    end
+
+    def configure_xai(config, env)
+      return unless env['XAI_API_KEY']
+
+      config.add_provider(
+        :xai,
+        Prescient::Provider::XAI,
+        api_key:    env['XAI_API_KEY'],
+        chat_model: env.fetch('XAI_CHAT_MODEL', 'grok-4.5'),
+      )
+    end
+
+    def configure_mistral(config, env)
+      return unless env['MISTRAL_API_KEY']
+
+      config.add_provider(
+        :mistral,
+        Prescient::Provider::Mistral,
+        api_key:         env['MISTRAL_API_KEY'],
+        embedding_model: env.fetch('MISTRAL_EMBEDDING_MODEL', 'mistral-embed'),
+        chat_model:      env.fetch('MISTRAL_CHAT_MODEL', 'mistral-large-latest'),
+      )
+    end
   end
 
   # Default configuration