prescient 0.4.0 → 0.6.0

data/lib/prescient/cli.rb

@@ -2,6 +2,8 @@
 
 require 'json'
 require 'optparse'
+require 'yaml'
+require_relative '../prescient'
 
 # Command-line interface for common Prescient operations.
 class Prescient::CLI
@@ -9,6 +11,90 @@ class Prescient::CLI
   # @return [Array<String>] Output format names
   FORMATS = ['text', 'json'].freeze
 
+  # Schema URL and annotated starter configuration for `config example`.
+  CONFIGURATION_EXAMPLE = <<~YAML
+    # yaml-language-server: $schema=https://raw.githubusercontent.com/kanutocd/prescient/refs/heads/main/schema/prescient.configuration.schema.json
+    #
+    # Prescient configuration example.
+    #
+    # Precedence, from lowest to highest:
+    # 1. Built-in defaults and provider environment variables.
+    # 2. Values in this YAML file.
+    # 3. Per-operation CLI overrides such as --provider and --chat-model.
+    #
+    # Use `prescient config validate` after editing this file.
+    # Keep credentials out of source control; use *_env references instead.
+    version: 1
+
+    # Global behavior.
+    default_provider: ollama
+    timeout: 30
+    retry_attempts: 3
+    retry_delay: 1.0
+    fallback_providers: []
+    sensitive_keys:
+      - api_key
+      - password
+      - token
+      - secret
+
+    providers:
+      # Local Ollama requires no API key.
+      ollama:
+        type: ollama
+        url: http://localhost:11434
+        embedding_model: nomic-embed-text
+        chat_model: llama3.2:3b
+        # prompt_templates:
+        #   system_prompt: You are a concise assistant.
+        #   no_context_template: "%<system_prompt>s\\n\\nUser: %<query>s"
+        #   with_context_template: "%<system_prompt>s\\n\\nContext:\\n%<context>s\\n\\nUser: %<query>s"
+
+      # Uncomment a cloud provider and set its credential in the environment.
+      # openai:
+      #   type: openai
+      #   api_key_env: OPENAI_API_KEY
+      #   embedding_model: text-embedding-3-small
+      #   chat_model: gpt-4.1-mini
+      #   prompt_templates:
+      #     system_prompt: You are a concise assistant.
+      #     no_context_template: "%<system_prompt>s\n\nUser: %<query>s"
+
+      # anthropic:
+      #   type: anthropic
+      #   api_key_env: ANTHROPIC_API_KEY
+      #   model: claude-sonnet-4-20250514
+
+      # gemini:
+      #   type: gemini
+      #   api_key_env: GEMINI_API_KEY
+      #   embedding_model: gemini-embedding-001
+      #   chat_model: gemini-2.5-flash
+
+      # mistral:
+      #   type: mistral
+      #   api_key_env: MISTRAL_API_KEY
+      #   embedding_model: mistral-embed
+      #   chat_model: mistral-large-latest
+
+      # DeepSeek supports text generation, but not embeddings.
+      # deepseek:
+      #   type: deepseek
+      #   api_key_env: DEEPSEEK_API_KEY
+      #   chat_model: deepseek-v4-flash
+
+      # xai:
+      #   type: xai
+      #   api_key_env: XAI_API_KEY
+      #   chat_model: grok-4.5
+
+      # huggingface:
+      #   type: huggingface
+      #   api_key_env: HUGGINGFACE_API_KEY
+      #   embedding_model: sentence-transformers/all-MiniLM-L6-v2
+      #   chat_model: google/gemma-2-2b-it
+  YAML
+
   # Raised when command-line arguments are invalid or incomplete.
   class UsageError < StandardError; end
 
@@ -42,10 +128,22 @@ class Prescient::CLI
     @errors = errors
   end
 
+  # Execute the CLI command and return its process status.
+  # @return [Integer] Process exit status
   def run
+    config_path = extract_global_config_path
+    Prescient.load_configuration(config_path) if config_path || ENV['PRESCIENT_CONFIG']
+
     command = @arguments.shift
     return print_help(2) unless command
 
+    run_command(command)
+  end
+
+  # Dispatch a parsed command to its handler.
+  # @param command [String] Command name
+  # @return [Integer] Process exit status
+  def run_command(command)
     case command
     when 'providers' then providers
     when 'health' then health
@@ -118,8 +216,15 @@ class Prescient::CLI
 
   def config
     subcommand = @arguments.shift
-    raise UsageError, "unknown config command #{subcommand.inspect}" unless subcommand == 'validate'
+    case subcommand
+    when 'validate' then validate_config_command
+    when 'example' then configuration_example_command
+    else
+      raise UsageError, "unknown config command #{subcommand.inspect}"
+    end
+  end
 
+  def validate_config_command
     options = parse_options('Validate the current configuration')
     return options if options.is_a?(Integer)
 
@@ -132,6 +237,14 @@ class Prescient::CLI
     0
   end
 
+  def configuration_example_command
+    options = parse_options('Generate an annotated YAML configuration example')
+    return options if options.is_a?(Integer)
+
+    @output.write(CONFIGURATION_EXAMPLE)
+    0
+  end
+
   def validate_configuration
     configuration = Prescient.configuration
     unless configuration.provider(configuration.default_provider)
@@ -162,6 +275,9 @@ class Prescient::CLI
   end
 
   def add_common_options(parser, options)
+    parser.on('--config PATH', 'Load configuration from a YAML file') do |value|
+      options[:config] = value
+    end
     parser.on('--format FORMAT', FORMATS, "Output format (#{FORMATS.join(', ')})") do |value|
       options[:format] = value
     end
@@ -206,6 +322,18 @@ class Prescient::CLI
     parser.on('--chat-model NAME', 'Override the chat model') do |value|
       options[:chat_model] = value
     end
+    parser.on('--system-prompt TEXT', 'Override the system prompt') do |value|
+      options[:system_prompt] = value
+    end
+    parser.on('--no-context-template TEXT', 'Override the no-context prompt template') do |value|
+      options[:no_context_template] = value
+    end
+    parser.on('--with-context-template TEXT', 'Override the with-context prompt template') do |value|
+      options[:with_context_template] = value
+    end
+    parser.on('--prompt-templates-file PATH', 'Load prompt templates from a YAML file') do |value|
+      options[:prompt_templates_file] = value
+    end
   end
 
   def add_credential_options(parser, options)
@@ -228,12 +356,38 @@ class Prescient::CLI
 
   def provider_options(options)
     {
-      api_key:         api_key_override(options),
-      embedding_model: options[:embedding_model],
-      chat_model:      options[:chat_model],
+      api_key:          api_key_override(options),
+      embedding_model:  options[:embedding_model],
+      chat_model:       options[:chat_model],
+      prompt_templates: prompt_templates(options),
     }.compact
   end
 
+  def prompt_templates(options)
+    templates = if options[:prompt_templates_file]
+                  data = YAML.safe_load_file(
+                    options[:prompt_templates_file],
+                    permitted_classes: [],
+                    permitted_symbols: [],
+                    aliases:           true,
+                  )
+                  raise UsageError, 'prompt templates file must contain a mapping' unless data.is_a?(Hash)
+
+                  data.transform_keys(&:to_sym)
+                else
+                  {}
+                end
+
+    [:system_prompt, :no_context_template, :with_context_template].each do |key|
+      templates[key] = options[key] if options[key]
+    end
+    templates.empty? ? nil : templates
+  rescue Errno::ENOENT
+    raise UsageError, "prompt templates file not found: #{options[:prompt_templates_file]}"
+  rescue Psych::SyntaxError => e
+    raise UsageError, "invalid prompt templates YAML: #{e.message}"
+  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]
@@ -272,16 +426,55 @@ class Prescient::CLI
         generate TEXT   Generate a text response
         embed TEXT      Generate an embedding
         config validate Validate the current configuration
+        config example  Generate an annotated YAML configuration example
 
       Options:
+        --config PATH            Load configuration from a YAML file
         --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
+        --system-prompt TEXT     Override the system prompt
+        --no-context-template TEXT
+                                 Override the no-context prompt template
+        --with-context-template TEXT
+                                 Override the with-context prompt template
+        --prompt-templates-file PATH
+                                 Load prompt templates from a YAML file
         --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
+
+  def extract_global_config_path
+    config_path = nil
+    filtered_arguments = []
+    index = 0
+
+    while index < @arguments.length
+      argument = @arguments[index]
+      if argument == '--config'
+        value = @arguments[index + 1]
+        raise UsageError, '--config requires a path' unless value
+
+        config_path = value
+        index += 2
+        next
+      end
+
+      if argument.start_with?('--config=')
+        config_path = argument.split('=', 2).last
+        index += 1
+        next
+      end
+
+      filtered_arguments << argument
+      index += 1
+    end
+
+    @arguments = filtered_arguments
+    config_path
+  end
 end

data/lib/prescient/configuration_loader.rb

@@ -0,0 +1,437 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+# Load and validate Prescient configuration data from YAML.
+class Prescient::ConfigurationLoader
+  # Supported YAML configuration schema version.
+  CONFIGURATION_VERSION = 1
+
+  # Allowed top-level configuration keys.
+  TOP_LEVEL_KEYS = [
+    '$schema',
+    'default_provider',
+    'default_provider_env',
+    'fallback_providers',
+    'fallback_providers_env',
+    'providers',
+    'retry_attempts',
+    'retry_attempts_env',
+    'retry_delay',
+    'retry_delay_env',
+    'sensitive_keys',
+    'sensitive_keys_env',
+    'timeout',
+    'timeout_env',
+    'version',
+  ].freeze
+
+  # Provider names mapped to their adapter classes.
+  PROVIDER_TYPES = {
+    'ollama'      => Prescient::Provider::Ollama,
+    'anthropic'   => Prescient::Provider::Anthropic,
+    'openai'      => Prescient::Provider::OpenAI,
+    'huggingface' => Prescient::Provider::HuggingFace,
+    'gemini'      => Prescient::Provider::Gemini,
+    'mistral'     => Prescient::Provider::Mistral,
+    'deepseek'    => Prescient::Provider::DeepSeek,
+    'xai'         => Prescient::Provider::XAI,
+  }.freeze
+
+  # Provider-specific keys shared by all supported adapters.
+  COMMON_PROVIDER_KEYS = [
+    'api_key',
+    'api_key_env',
+    'chat_model',
+    'chat_model_env',
+    'context_configs',
+    'context_configs_env',
+    'embedding_dimensions',
+    'embedding_dimensions_env',
+    'embedding_model',
+    'embedding_model_env',
+    'model',
+    'model_env',
+    'prompt_templates',
+    'prompt_templates_env',
+    'timeout',
+    'timeout_env',
+    'url',
+    'url_env',
+  ].freeze
+
+  # Prompt template keys supported by provider configuration.
+  PROMPT_TEMPLATE_KEYS = ['system_prompt', 'no_context_template', 'with_context_template'].freeze
+
+  # Configuration attributes supported by the loader.
+  ATTR_KEYS = [
+    'default_provider',
+    'fallback_providers',
+    'retry_attempts',
+    'retry_delay',
+    'sensitive_keys',
+    'timeout',
+  ].freeze
+
+  class << self
+    # Load and validate configuration from a YAML file.
+    # @param path [String] Configuration file path
+    # @param env [Hash] Environment variables used during expansion
+    # @return [Prescient::Configuration] Loaded configuration
+    def load_file(path, env: ENV)
+      new(env).load_file(path)
+    end
+
+    # Load and validate configuration from YAML content.
+    # @param content [String] YAML configuration content
+    # @param env [Hash] Environment variables used during expansion
+    # @return [Prescient::Configuration] Loaded configuration
+    def load_yaml(content, env: ENV)
+      new(env).load_yaml(content)
+    end
+
+    # Load and validate configuration from a Ruby hash.
+    # @param data [Hash] Configuration data
+    # @param env [Hash] Environment variables used during expansion
+    # @return [Prescient::Configuration] Loaded configuration
+    def load_hash(data, env: ENV)
+      new(env).load_hash(data)
+    end
+  end
+
+  def initialize(env = ENV)
+    @env = env
+  end
+
+  # Load configuration from a YAML file.
+  # @param path [String] Configuration file path
+  # @return [Prescient::Configuration] Loaded configuration
+  def load_file(path)
+    load_yaml(File.read(path), source: path)
+  rescue Errno::ENOENT
+    raise Prescient::Error, "Configuration file not found: #{path}"
+  end
+
+  # Load configuration from YAML content.
+  # @param content [String] YAML configuration content
+  # @param source [String, nil] Source label used in validation errors
+  # @return [Prescient::Configuration] Loaded configuration
+  def load_yaml(content, source: nil)
+    data = YAML.safe_load(content, permitted_classes: [], permitted_symbols: [], aliases: true)
+    load_hash(data || {}, source:)
+  rescue Psych::SyntaxError => e
+    raise Prescient::Error, "Invalid YAML configuration#{" in #{source}" if source}: #{e.message}"
+  end
+
+  # Load configuration from a Ruby hash.
+  # @param data [Hash] Configuration data
+  # @param source [String, nil] Source label used in validation errors
+  # @return [Prescient::Configuration] Loaded configuration
+  def load_hash(data, source: nil)
+    configuration = Prescient::Configuration.new
+    Prescient.send(:configure_default_providers, configuration, @env)
+    apply!(configuration, data, source:)
+    configuration
+  end
+
+  # Apply validated configuration data to an existing configuration object.
+  # @param configuration [Prescient::Configuration] Target configuration
+  # @param data [Hash] Configuration data
+  # @param source [String, nil] Source label used in validation errors
+  # @return [Prescient::Configuration] Updated configuration
+  def apply!(configuration, data, source: nil)
+    normalized = normalize_keys(data)
+    validate_root!(normalized, source:)
+    validate_version!(normalized, source:)
+
+    apply_scalar_settings(configuration, normalized, source:)
+    apply_provider_settings(configuration, normalized, source:)
+    configuration
+  end
+
+  # Return the packaged JSON Schema path.
+  # @return [String] Absolute path to the configuration schema
+  def self.schema_path
+    File.expand_path('../../schema/prescient.configuration.schema.json', __dir__)
+  end
+
+  private
+
+  def validate_root!(data, source:)
+    unless data.is_a?(Hash)
+      raise Prescient::Error, "Configuration#{" in #{source}" if source} must be a mapping"
+    end
+
+    unknown_keys = data.keys.map(&:to_s) - TOP_LEVEL_KEYS
+    return if unknown_keys.empty?
+
+    raise Prescient::Error,
+          "Unknown configuration key#{'s' if unknown_keys.length > 1}: #{unknown_keys.join(', ')}" \
+          "#{" in #{source}" if source}"
+  end
+
+  def apply_scalar_settings(configuration, data, source:)
+    apply_default_provider(configuration, data, source:)
+    apply_numeric_settings(configuration, data, source:)
+    apply_collection_settings(configuration, data, source:)
+  end
+
+  def apply_default_provider(configuration, data, source:)
+    return unless scalar_present?(data, :default_provider)
+
+    default_provider = resolve_scalar(data, :default_provider, source:)
+    if default_provider.nil? || default_provider.to_s.empty?
+      raise Prescient::Error, 'default_provider must be a non-empty string'
+    end
+
+    configuration.default_provider = default_provider.to_sym
+  end
+
+  def apply_numeric_settings(configuration, data, source:)
+    numeric_settings = {
+      timeout:        [:coerce_integer, 'timeout'],
+      retry_attempts: [:coerce_integer, 'retry_attempts'],
+      retry_delay:    [:coerce_float, 'retry_delay'],
+    }
+
+    numeric_settings.each do |key, (coercer, name)|
+      next unless scalar_present?(data, key)
+
+      value = resolve_scalar(data, key, source:)
+      setter = "#{key}="
+      configuration.public_send(setter, send(coercer, value, name))
+    end
+  end
+
+  def apply_collection_settings(configuration, data, source:)
+    if scalar_present?(data, :fallback_providers)
+      value = resolve_scalar(data, :fallback_providers, source:)
+      configuration.fallback_providers = Array(value).map(&:to_sym)
+    end
+
+    return unless scalar_present?(data, :sensitive_keys)
+
+    configuration.sensitive_keys = Array(resolve_scalar(data, :sensitive_keys, source:))
+  end
+
+  def apply_provider_settings(configuration, data, source:)
+    return unless key_present?(data, :providers)
+
+    providers = data[:providers]
+    unless providers.is_a?(Hash)
+      raise Prescient::Error, "Configuration#{" in #{source}" if source} providers must be a mapping"
+    end
+
+    providers.each do |name, provider_data|
+      provider_name = name.to_sym
+      provider_settings = normalize_keys(provider_data)
+      validate_provider!(provider_name, provider_settings, source:)
+
+      provider_options = resolve_provider_options(provider_settings, source:)
+      configuration.add_provider(provider_name, PROVIDER_TYPES[provider_settings.fetch(:type).to_s],
+                                 **provider_options)
+    end
+  end
+
+  def validate_provider!(name, provider_data, source:)
+    validate_provider_shape!(name, provider_data, source:)
+    validate_provider_type!(name, provider_data, source:)
+    validate_provider_keys!(name, provider_data, source:)
+    validate_prompt_templates!(name, provider_data, source:)
+  end
+
+  def validate_provider_shape!(name, provider_data, source:)
+    return if provider_data.is_a?(Hash)
+
+    raise Prescient::Error, "Provider #{name.inspect}#{" in #{source}" if source} must be a mapping"
+  end
+
+  def validate_provider_type!(name, provider_data, source:)
+    return if provider_data.key?(:type)
+
+    raise Prescient::Error, "Provider #{name}#{" in #{source}" if source} must define type"
+  end
+
+  def validate_provider_keys!(name, provider_data, source:)
+    unknown_keys = provider_data.keys.map(&:to_s) - (['type'] + COMMON_PROVIDER_KEYS)
+    return if unknown_keys.empty?
+
+    raise Prescient::Error,
+          "Unknown provider configuration key#{'s' if unknown_keys.length > 1} for #{name}: " \
+          "#{unknown_keys.join(', ')}" \
+          "#{" in #{source}" if source}"
+  end
+
+  def validate_prompt_templates!(name, provider_data, source:)
+    templates = provider_data[:prompt_templates]
+    return if templates.nil?
+
+    source_suffix = " in #{source}" if source
+    unless templates.is_a?(Hash)
+      raise Prescient::Error, "prompt_templates for #{name} must be a mapping#{source_suffix}"
+    end
+
+    unknown_keys = templates.keys.map(&:to_s) - PROMPT_TEMPLATE_KEYS
+    return if unknown_keys.empty?
+
+    message = "Unknown prompt template key#{'s' if unknown_keys.length > 1} for #{name}: " \
+              "#{unknown_keys.join(', ')}#{source_suffix}"
+    raise Prescient::Error, message
+  end
+
+  def resolve_provider_options(provider_data, source:)
+    provider_type = provider_data[:type].to_s
+    provider_class = PROVIDER_TYPES[provider_type]
+    unless provider_class
+      raise Prescient::Error,
+            "Unknown provider type #{provider_type.inspect}#{" in #{source}" if source}"
+    end
+
+    provider_data.each_with_object({}) do |(key, value), options|
+      option = resolve_provider_option(provider_data, key, value, source:)
+      options[option.first] = option.last if option
+    end
+  end
+
+  def resolve_provider_option(provider_data, key, value, source:)
+    return if key == :type
+    return if key.to_s.end_with?('_env') && value.nil?
+
+    if key.to_s.end_with?('_env')
+      base_key = key.to_s.delete_suffix('_env').to_sym
+      if provider_data.key?(base_key)
+        raise Prescient::Error,
+              "Provider configuration cannot combine #{base_key} and #{key}"
+      end
+
+      [base_key, resolve_env_value(value, source:)]
+    else
+      [key, coerce_provider_option(key, resolve_value(value, source:))]
+    end
+  end
+
+  def resolve_scalar(data, key, source:)
+    env_key = :"#{key}_env"
+    if key_present?(data, key) && key_present?(data, env_key)
+      raise Prescient::Error, "Configuration cannot combine #{key} and #{key}_env"
+    end
+
+    return resolve_env_value(data[env_key], source:) if key_present?(data, env_key)
+
+    value = data[key]
+    return nil if value.nil?
+
+    resolve_value(value, source:)
+  end
+
+  def resolve_value(value, source:)
+    case value
+    when Hash
+      resolve_hash_value(value, source:)
+    when Array
+      value.map { |item| resolve_value(item, source:) }
+    when String
+      interpolate_env(value, source:)
+    else
+      value
+    end
+  end
+
+  def resolve_hash_value(value, source:)
+    value.each_with_object({}) do |(key, nested_value), result|
+      key_name = key.to_s
+      if key_name.end_with?('_env')
+        base_key = key_name.delete_suffix('_env').to_sym
+        if value.key?(base_key) || value.key?(base_key.to_s)
+          raise Prescient::Error, "Configuration cannot combine #{base_key} and #{key_name}"
+        end
+
+        result[base_key] = resolve_env_value(nested_value, source:)
+      else
+        result[key.to_sym] = resolve_value(nested_value, source:)
+      end
+    end
+  end
+
+  def resolve_env_value(value, source:)
+    env_name = resolve_value(value, source:)
+    unless env_name.is_a?(String) && !env_name.empty?
+      raise Prescient::Error, 'Environment variable name must be a non-empty string'
+    end
+
+    raw_value = @env.fetch(env_name)
+    parsed_value = YAML.safe_load(raw_value, permitted_classes: [], permitted_symbols: [], aliases: true)
+    parsed_value.nil? ? raw_value : parsed_value
+  rescue KeyError
+    raise Prescient::Error, "Environment variable not set: #{env_name}#{" in #{source}" if source}"
+  end
+
+  def interpolate_env(value, source:)
+    value.gsub(/\$\{([A-Z0-9_]+)\}/) do
+      env_name = Regexp.last_match(1)
+      @env.fetch(env_name)
+    rescue KeyError
+      raise Prescient::Error, "Environment variable not set: #{env_name}#{" in #{source}" if source}"
+    end
+  end
+
+  def normalize_keys(value)
+    case value
+    when Hash
+      value.each_with_object({}) do |(key, nested_value), result|
+        result[key.to_sym] = normalize_keys(nested_value)
+      end
+    when Array
+      value.map { |item| normalize_keys(item) }
+    else
+      value
+    end
+  end
+
+  def key_present?(data, key)
+    data.key?(key) || data.key?(key.to_s)
+  end
+
+  def scalar_present?(data, key)
+    key_present?(data, key) || key_present?(data, :"#{key}_env")
+  end
+
+  def coerce_integer(value, name)
+    return value if value.is_a?(Integer)
+    return value.to_i if value.is_a?(Numeric)
+
+    Integer(value)
+  rescue ArgumentError, TypeError
+    raise Prescient::Error, "#{name} must be an integer"
+  end
+
+  def coerce_float(value, name)
+    return value.to_f if value.is_a?(Numeric)
+
+    Float(value)
+  rescue ArgumentError, TypeError
+    raise Prescient::Error, "#{name} must be a number"
+  end
+
+  def coerce_provider_option(key, value)
+    case key.to_sym
+    when :embedding_dimensions
+      coerce_integer(value, 'embedding_dimensions')
+    when :timeout
+      coerce_integer(value, 'timeout')
+    else
+      value
+    end
+  end
+
+  def validate_version!(data, source:)
+    return unless key_present?(data, :version)
+
+    version = resolve_value(data[:version], source:)
+    return if version == CONFIGURATION_VERSION
+
+    raise Prescient::Error,
+          "Unsupported configuration version #{version.inspect}#{" in #{source}" if source}"
+  end
+end