prescient 0.3.0 → 0.5.0

data/lib/prescient.rb

@@ -8,7 +8,13 @@ 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'
 
 # Main Prescient module for AI provider abstraction
 #
@@ -60,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
@@ -166,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(
@@ -205,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

data/schema/prescient.configuration.schema.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kanutocd/prescient/schema/prescient.configuration.schema.json",
+  "title": "Prescient Configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "default_provider": {
+      "type": "string"
+    },
+    "default_provider_env": {
+      "type": "string"
+    },
+    "timeout": {
+      "type": "number"
+    },
+    "timeout_env": {
+      "type": "string"
+    },
+    "retry_attempts": {
+      "type": "integer"
+    },
+    "retry_attempts_env": {
+      "type": "string"
+    },
+    "retry_delay": {
+      "type": "number"
+    },
+    "retry_delay_env": {
+      "type": "string"
+    },
+    "fallback_providers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "fallback_providers_env": {
+      "type": "string"
+    },
+    "sensitive_keys": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "sensitive_keys_env": {
+      "type": "string"
+    },
+    "providers": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/provider"
+      }
+    }
+  },
+  "$defs": {
+    "provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "ollama",
+            "anthropic",
+            "openai",
+            "huggingface",
+            "gemini",
+            "mistral",
+            "deepseek",
+            "xai"
+          ]
+        },
+        "api_key": {
+          "type": "string"
+        },
+        "api_key_env": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "url_env": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        },
+        "model_env": {
+          "type": "string"
+        },
+        "chat_model": {
+          "type": "string"
+        },
+        "chat_model_env": {
+          "type": "string"
+        },
+        "embedding_model": {
+          "type": "string"
+        },
+        "embedding_model_env": {
+          "type": "string"
+        },
+        "embedding_dimensions": {
+          "type": "integer"
+        },
+        "embedding_dimensions_env": {
+          "type": "string"
+        },
+        "timeout": {
+          "type": "number"
+        },
+        "timeout_env": {
+          "type": "string"
+        },
+        "context_configs": {
+          "type": "object"
+        },
+        "context_configs_env": {
+          "type": "string"
+        },
+        "prompt_templates": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "system_prompt": {
+              "type": "string"
+            },
+            "no_context_template": {
+              "type": "string"
+            },
+            "with_context_template": {
+              "type": "string"
+            }
+          }
+        },
+        "prompt_templates_env": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

data/sig/prescient.rbs

@@ -154,6 +154,82 @@ module Prescient
       def validate_configuration!: () -> void
       def validate_response!: (untyped, String) -> void
     end
+
+    class Gemini < Base
+      def self.base_uri: (String) -> untyped
+      def self.default_timeout: (Integer) -> untyped
+      def self.get: (String, **untyped) -> untyped
+      def self.post: (String, **untyped) -> untyped
+
+      def initialize: (**untyped) -> void
+      def generate_embedding: (String, **untyped) -> Array[Float]
+      def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+      def health_check: () -> Hash[Symbol, untyped]
+      def list_models: () -> Array[Hash[Symbol, untyped]]
+
+      private
+
+      def validate_configuration!: () -> void
+      def api_headers: () -> Hash[String, String]
+      def model_endpoint: (untyped, String) -> String
+      def find_model: (Array[untyped], untyped, String) -> bool
+    end
+
+    class Mistral < Base
+      def self.base_uri: (String) -> untyped
+      def self.default_timeout: (Integer) -> untyped
+      def self.get: (String, **untyped) -> untyped
+      def self.post: (String, **untyped) -> untyped
+
+      def initialize: (**untyped) -> void
+      def generate_embedding: (String, **untyped) -> Array[Float]
+      def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+      def health_check: () -> Hash[Symbol, untyped]
+      def list_models: () -> Array[Hash[Symbol, untyped]]
+
+      private
+
+      def validate_configuration!: () -> void
+      def api_headers: () -> Hash[String, String]
+      def model_available?: (Array[untyped], untyped) -> bool
+      def normalize_content: (untyped) -> String?
+    end
+
+    class DeepSeek < Base
+      def self.base_uri: (String) -> untyped
+      def self.default_timeout: (Integer) -> untyped
+      def self.get: (String, **untyped) -> untyped
+      def self.post: (String, **untyped) -> untyped
+
+      def initialize: (**untyped) -> void
+      def generate_embedding: (String, **untyped) -> untyped
+      def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+      def health_check: () -> Hash[Symbol, untyped]
+      def list_models: () -> Array[Hash[Symbol, untyped]]
+
+      private
+
+      def validate_configuration!: () -> void
+      def api_headers: () -> Hash[String, String]
+    end
+
+    class XAI < Base
+      def self.base_uri: (String) -> untyped
+      def self.default_timeout: (Integer) -> untyped
+      def self.get: (String, **untyped) -> untyped
+      def self.post: (String, **untyped) -> untyped
+
+      def initialize: (**untyped) -> void
+      def generate_embedding: (String, **untyped) -> untyped
+      def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+      def health_check: () -> Hash[Symbol, untyped]
+      def list_models: () -> Array[Hash[Symbol, untyped]]
+
+      private
+
+      def validate_configuration!: () -> void
+      def api_headers: () -> Hash[String, String]
+    end
   end
 
   module Pgvector
@@ -193,7 +269,7 @@ module Prescient
     attr_reader provider_name: Symbol
     attr_reader provider: untyped
 
-    def initialize: (?Symbol, ?enable_fallback: bool) -> void
+    def initialize: (?Symbol, ?enable_fallback: bool, ?provider_options: Hash[Symbol, untyped]) -> void
     def generate_embedding: (String, **untyped) -> Array[Float]
     def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
     def health_check: () -> Hash[Symbol, untyped]
@@ -203,6 +279,7 @@ module Prescient
     private
 
     def sanitize_options: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def provider_with_options: (Symbol, Hash[Symbol, untyped]) -> untyped
     def with_error_handling: () { () -> untyped } -> untyped
     def with_fallback_handling: (Symbol, *untyped, **untyped) -> untyped
     def provider_for: (Symbol, Integer) -> untyped
@@ -210,10 +287,42 @@ module Prescient
     def fallback_eligible?: (Error) -> bool
   end
 
+  class CLI
+    FORMATS: Array[String]
+
+    class UsageError < StandardError
+    end
+
+    def self.run: (Array[String], ?input: IO, ?output: IO, ?errors: IO) -> Integer
+    def initialize: (Array[String], input: IO, output: IO, errors: IO) -> void
+    def run: () -> Integer
+  end
+
+  class ConfigurationLoader
+    CONFIGURATION_VERSION: Integer
+    TOP_LEVEL_KEYS: Array[String]
+    PROVIDER_TYPES: Hash[String, untyped]
+    COMMON_PROVIDER_KEYS: Array[String]
+    PROMPT_TEMPLATE_KEYS: Array[String]
+    ATTR_KEYS: Array[String]
+
+    def self.load_file: (String, ?env: untyped) -> Configuration
+    def self.load_yaml: (String, ?env: untyped) -> Configuration
+    def self.load_hash: (Hash[untyped, untyped], ?env: untyped) -> Configuration
+    def self.schema_path: () -> String
+
+    def initialize: (?untyped) -> void
+    def load_file: (String) -> Configuration
+    def load_yaml: (String, ?source: String?) -> Configuration
+    def load_hash: (untyped, ?source: String?) -> Configuration
+    def apply!: (Configuration, untyped, ?source: String?) -> Configuration
+  end
+
   def self.configure: () { (Configuration) -> void } -> void
   def self.configuration: () -> Configuration
   def self.reset_configuration!: () -> Configuration
-  def self.client: (?Symbol, ?enable_fallback: bool) -> Client
+  def self.load_configuration: (?String?, ?env: untyped) -> Configuration
+  def self.client: (?Symbol, ?enable_fallback: bool, ?provider_options: Hash[Symbol, untyped]) -> Client
   def self.generate_embedding: (String, ?provider: Symbol, ?enable_fallback: bool, **untyped) -> Array[Float]
   def self.generate_response: (String, ?Array[untyped], ?provider: Symbol, ?enable_fallback: bool, **untyped) -> Hash[Symbol, untyped]
   def self.health_check: (?provider: Symbol) -> Hash[Symbol, untyped]
@@ -221,4 +330,12 @@ module Prescient
   private
 
   def self.configure_default_providers: (Configuration, untyped) -> void
+  def self.configure_ollama: (Configuration, untyped) -> void
+  def self.configure_openai: (Configuration, untyped) -> void
+  def self.configure_anthropic: (Configuration, untyped) -> void
+  def self.configure_gemini: (Configuration, untyped) -> void
+  def self.configure_mistral: (Configuration, untyped) -> void
+  def self.configure_deepseek: (Configuration, untyped) -> void
+  def self.configure_xai: (Configuration, untyped) -> void
+  def self.configure_huggingface: (Configuration, untyped) -> void
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prescient
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -28,7 +28,8 @@ description: "Prescient provides a consistent interface for AI providers includi
   health checks, and automatic fallback.\n"
 email:
 - kenneth.c.demanawa@gmail.com
-executables: []
+executables:
+- prescient
 extensions: []
 extra_rdoc_files: []
 files:
@@ -55,16 +56,24 @@ files:
 - examples/custom_contexts.rb
 - examples/custom_prompts.rb
 - examples/vector_search.rb
+- exe/prescient
 - lib/prescient.rb
 - lib/prescient/base.rb
+- lib/prescient/cli.rb
 - lib/prescient/client.rb
+- lib/prescient/configuration_loader.rb
 - lib/prescient/errors.rb
 - lib/prescient/pgvector.rb
 - lib/prescient/provider/anthropic.rb
+- lib/prescient/provider/deepseek.rb
+- lib/prescient/provider/gemini.rb
 - lib/prescient/provider/huggingface.rb
+- lib/prescient/provider/mistral.rb
 - lib/prescient/provider/ollama.rb
 - lib/prescient/provider/openai.rb
+- lib/prescient/provider/xai.rb
 - lib/prescient/version.rb
+- schema/prescient.configuration.schema.json
 - scripts/setup-ollama-models.sh
 - sig/prescient.rbs
 homepage: https://kanutocd.github.io/prescient