prescient 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a54256e23ba55fc2492fae38d687b275dcb2362df73449d3212bd03659150717
-  data.tar.gz: 73ab805b7a5781a1d03488605ae8d7890feda7344b41b1ac550343484b3b597a
+  metadata.gz: 3f12c7d49067ef7917aa1f674f83e4ff8111a5606fa62edcbb7c97b8791dfbee
+  data.tar.gz: 4bf6ad2a1a8988ec7eb77cb5a2e278f902ceaa2cfc30d0de3c303c4fa1017168
 SHA512:
-  metadata.gz: e918a87b3e09affe9d5a002a3955051e7729ee565f84c42c534c99dc3fc70371fda930e63cc90801da07b4c4f5e48031c41e952088dfc3de24f0f38b579e9567
-  data.tar.gz: feb707947b7cc0b67d8bff933b4c584a69595b9b5e1dd3f214b4c4aa2d48c0577c996b542c238fbcef337f0f276a1bb995acc9653e8fad32262a6f6fa17caaf4
+  metadata.gz: b0fd6efd2a47ce4ffd2766d32706b4b852bfb4e47b62b10ca5e39b50698281048d15be905cfcace617185958194bd1fccde939fd4bac1d83d617cf72707a54c5
+  data.tar.gz: dfeb2ac6ed61f430730c589a42853b0d118cb425871784dc481e6ea781fedbfd6fcd3582cdadf89718b01c97a2da234898b8bbd868fc709ce3582c02e0662bee

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## [0.4.0] - 2025-08-14
+
+### Added
+
+- Added the `prescient` CLI with provider listing, health checks, configuration validation, generation, embeddings, JSON output, stdin input, and exit-status handling.
+
+### Changed
+
+- Added CLI model overrides to provider generation and embedding operations.
+- Added secure CLI credential sourcing with `--api-key-env`, alongside direct `--api-key` support for ephemeral automation.
+- Documented all CLI automation overrides, including provider selection, generic and task-specific models, API keys, environment-backed credentials, and JSON output.
+
 ## [0.3.0] - 2025-08-14
 
 ### Added

data/INTEGRATION_GUIDE.md

@@ -13,7 +13,7 @@ and [examples guide](examples/README.md).
 # Add to your Gemfile
 gem 'prescient', path: './prescient_gem'  # Local development
 # OR when published:
-# gem 'prescient', '~> 0.3.0'
+# gem 'prescient', '~> 0.4.0'
 ```
 
 ### 2. Replace Existing AI Service

data/README.md

@@ -2,9 +2,9 @@
 
 Prescient is a boring AI provider abstraction for Ruby. Configure your AI providers once, then use the same interface regardless of whether the request is handled by OpenAI, Anthropic, Ollama, or Hugging Face. Prescient handles provider selection, retries, health checks, and fallback.
 
-For focused guidance, see the [examples guide](examples/README.md),
-[Rails integration guide](INTEGRATION_GUIDE.md), and
-[pgvector guide](VECTOR_SEARCH_GUIDE.md).
+For focused guidance, see the **[examples guide](https://github.com/kanutocd/prescient/tree/main/examples)**,
+**[Rails integration guide](https://github.com/kanutocd/prescient/blob/main/INTEGRATION_GUIDE.md)**, and
+**[pgvector guide](https://github.com/kanutocd/prescient/blob/main/VECTOR_SEARCH_GUIDE.md)**.
 
 ## Features
 
@@ -62,6 +62,90 @@ Or install it yourself as:
 gem install prescient
 ```
 
+## Command-Line Interface
+
+Prescient includes a thin CLI for provider inspection and common operations:
+
+```bash
+prescient providers
+prescient health
+prescient config validate
+prescient generate "Explain Ruby Ractors"
+prescient embed "Ruby is a programming language"
+```
+
+Supported options include:
+
+```text
+--provider NAME          Select a provider
+--model NAME             Override the selected operation's model
+--chat-model NAME        Override the chat model for generation
+--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          Select text or json output
+```
+
+Use `--api-key-env` to source credentials from an environment variable. The
+direct `--api-key` option is available for ephemeral automation but may be
+visible in shell history or process listings. Use `--format json` for
+machine-readable output and stdin for shell pipelines:
+
+```bash
+printf '%s' "Explain PostgreSQL logical replication" | \
+  prescient generate --provider openai --format json
+```
+
+Example JSON output:
+
+```json
+{
+    "response": "PostgreSQL logical replication is a method of replicating data between PostgreSQL databases at a logical level, allowing fine-grained control over which data is replicated and how. Unlike physical replication, which copies the entire database cluster’s data files at the storage level, logical replication works by sending changes to data (such as INSERT, UPDATE, DELETE operations) based on logical changes in the database.\n\n### Key Features of PostgreSQL Logical Replication\n\n1. **Row-Level Replication:** Logical replication replicates data changes at the row level. It streams changes to individual tables rather than the entire database.\n\n2. **Selective Replication:** You can choose specific tables to replicate rather than the whole database. This makes it useful for replicating subsets of data.\n\n3. **Asynchronous Replication:** Changes are sent asynchronously from the publisher (source) to the subscriber (target). This means there may be a slight delay between when changes are made and when they appear on the subscriber.\n\n4. **Supports Heterogeneous Setups:** Logical replication can be used between different major versions of PostgreSQL, allowing upgrades with minimal downtime. It can also be used for replication between different architectures or operating systems.\n\n5. **Bidirectional Replication:** By configuring multiple publishers and subscribers, logical replication can support multi-master setups, although care must be taken to avoid conflicts.\n\n### How Logical Replication Works\n\n- **Publisher:** The database that sends data changes. It defines one or more publications, which specify which tables and changes (inserts, updates, deletes) to replicate.\n  \n- **Subscriber:** The database that receives and applies the changes. It subscribes to one or more publications from the publisher.\n\nWhen a change occurs on the publisher's table, the change is captured and sent to the subscriber, where it is applied to the corresponding table.\n\n### Setting Up Logical Replication (Basic Steps)\n\n1. **Enable required settings:** Ensure the PostgreSQL server has `wal_level` set to `logical`, and configure `max_replication_slots` and `max_wal_senders` appropriately.\n\n2. **Create a publication on the publisher:**\n\n   ```sql\n   CREATE PUBLICATION my_publication FOR TABLE my_table;\n   ```\n\n3. **Create a subscription on the subscriber:**\n\n   ```sql\n   CREATE SUBSCRIPTION my_subscription\n   CONNECTION 'host=publisher_host dbname=publisher_db user=replicator password=secret'\n   PUBLICATION my_publication;\n   ```\n\nOnce set up, changes to `my_table` on the publisher will be replicated to the subscriber.\n\n### Use Cases\n\n- **Selective data replication:** Replicating only certain tables or rows.\n- **Data integration:** Feeding data from multiple sources into a central database.\n- **Upgrading PostgreSQL versions:** Using logical replication to migrate data with minimal downtime.\n- **Multi-datacenter replication:** Replicating data across geographically distributed systems.\n\n---\n\nIn summary, PostgreSQL logical replication is a flexible, table-level replication mechanism that allows selective, asynchronous replication of data changes between PostgreSQL databases, useful for upgrades, distributed architectures, and data integration scenarios.",
+    "model": "gpt-4.1-mini",
+    "provider": "openai",
+    "processing_time": null,
+    "metadata": {
+        "usage": {
+            "prompt_tokens": 38,
+            "completion_tokens": 632,
+            "total_tokens": 670,
+            "prompt_tokens_details": {
+                "cached_tokens": 0,
+                "audio_tokens": 0
+            },
+            "completion_tokens_details": {
+                "reasoning_tokens": 0,
+                "audio_tokens": 0,
+                "accepted_prediction_tokens": 0,
+                "rejected_prediction_tokens": 0
+            }
+        },
+        "finish_reason": "stop"
+    }
+}
+```
+
+For automated model and credential overrides:
+
+```bash
+prescient generate \
+  --provider openai \
+  --chat-model gpt-4.1-mini \
+  --api-key-env OPENAI_API_KEY \
+  --format json \
+  "Explain PostgreSQL logical replication"
+
+prescient embed \
+  --provider openai \
+  --embedding-model text-embedding-3-small \
+  --api-key-env OPENAI_API_KEY \
+  "Ruby is a programming language"
+```
+
+The CLI writes results to stdout, diagnostics to stderr, and returns a
+non-zero status for invalid usage, provider errors, or unreachable health
+checks. It uses the same `Prescient::Client` execution path as Ruby callers.
+
 ## Configuration
 
 ### Environment Variables

data/exe/prescient

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'prescient'
+require 'prescient/cli'
+
+exit Prescient::CLI.run(ARGV)

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

@@ -27,10 +27,11 @@ module Prescient
     #
     # @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 configured: #{@provider_name}" unless @provider
@@ -131,6 +132,16 @@ module Prescient
       end
     end
 
+    def provider_with_options(provider_name, provider_options)
+      return Prescient.configuration.provider(provider_name) if provider_options.empty?
+
+      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
       retries = 0
       begin
@@ -208,9 +219,10 @@ module Prescient
   #
   # @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)
-    Client.new(provider_name, enable_fallback: enable_fallback)
+  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.

data/lib/prescient/provider/anthropic.rb

@@ -37,7 +37,7 @@ class Prescient::Provider::Anthropic < Prescient::Base
                                    'anthropic-version' => '2023-06-01',
                                  },
                                  body:    {
-                                   model:       @options[:model],
+                                   model:       options[:model] || @options[:model],
                                    max_tokens:  options[:max_tokens] || 2000,
                                    temperature: options[:temperature] || 0.7,
                                    messages:    [
@@ -55,7 +55,7 @@ class Prescient::Provider::Anthropic < Prescient::Base
 
       {
         response:        content.strip,
-        model:           @options[:model],
+        model:           options[:model] || @options[:model],
         provider:        'anthropic',
         processing_time: nil,
         metadata:        {

data/lib/prescient/provider/huggingface.rb

@@ -35,11 +35,12 @@ class Prescient::Provider::HuggingFace < Prescient::Base
   # Generate an embedding through Hugging Face feature extraction.
   # @param text [String] Text to embed
   # @return [Array<Float>] Embedding vector
-  def generate_embedding(text, **_options)
+  def generate_embedding(text, **options)
     handle_errors do
       clean_text_input = clean_text(text)
 
-      response = self.class.post(FEATURE_EXTRACTION_PATH % { model: @options[:embedding_model] },
+      embedding_model = options[:model] || @options[:embedding_model]
+      response = self.class.post(FEATURE_EXTRACTION_PATH % { model: embedding_model },
                                  headers: {
                                    'Content-Type'  => 'application/json',
                                    'Authorization' => "Bearer #{@options[:api_key]}",
@@ -54,10 +55,10 @@ class Prescient::Provider::HuggingFace < Prescient::Base
 
       raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding_data.is_a?(Array)
 
-      expected_dimensions = EMBEDDING_DIMENSIONS[@options[:embedding_model]] || @options[:embedding_dimensions]
+      expected_dimensions = EMBEDDING_DIMENSIONS[embedding_model] || @options[:embedding_dimensions]
       unless expected_dimensions
         raise Prescient::Error,
-              "Embedding dimensions are required for model #{@options[:embedding_model]}"
+              "Embedding dimensions are required for model #{embedding_model}"
       end
 
       validate_embedding_dimensions(embedding_data, expected_dimensions)
@@ -78,7 +79,7 @@ class Prescient::Provider::HuggingFace < Prescient::Base
                                    'Authorization' => "Bearer #{@options[:api_key]}",
                                  },
                                  body:    {
-                                   model:       @options[:chat_model],
+                                   model:       options[:model] || @options[:chat_model],
                                    messages:    [{ role: 'user', content: formatted_prompt }],
                                    max_tokens:  options[:max_tokens] || 2000,
                                    temperature: options[:temperature] || 0.7,
@@ -93,7 +94,7 @@ class Prescient::Provider::HuggingFace < Prescient::Base
 
       {
         response:        generated_text.strip,
-        model:           @options[:chat_model],
+        model:           options[:model] || @options[:chat_model],
         provider:        'huggingface',
         processing_time: nil,
         metadata:        {

data/lib/prescient/provider/ollama.rb

@@ -21,7 +21,7 @@ class Prescient::Provider::Ollama < Prescient::Base
                                    root_key: 'embeddings',
                                    headers:  { 'Content-Type' => 'application/json' },
                                    body:     {
-                                     model: @options[:embedding_model],
+                                     model: options[:model] || @options[:embedding_model],
                                      input: clean_text(text),
                                    }.to_json)
 
@@ -55,7 +55,7 @@ class Prescient::Provider::Ollama < Prescient::Base
 
       {
         response:        generated_text.strip,
-        model:           @options[:chat_model],
+        model:           options[:model] || @options[:chat_model],
         provider:        'ollama',
         processing_time: response.parsed_response['total_duration']&./(1_000_000_000.0),
         metadata:        {
@@ -158,7 +158,7 @@ class Prescient::Provider::Ollama < Prescient::Base
     { root_key: 'response',
       headers:  { 'Content-Type' => 'application/json' },
       body:     {
-        model:   @options[:chat_model],
+        model:   options[:model] || @options[:chat_model],
         prompt:  formatted_prompt,
         stream:  false,
         options: {

data/lib/prescient/provider/openai.rb

@@ -23,17 +23,18 @@ class Prescient::Provider::OpenAI < Prescient::Base
   # Generate an embedding through the OpenAI embeddings API.
   # @param text [String] Text to embed
   # @return [Array<Float>] Embedding vector
-  def generate_embedding(text, **_options)
+  def generate_embedding(text, **options)
     handle_errors do
       clean_text_input = clean_text(text)
 
+      embedding_model = options[:model] || @options[:embedding_model]
       response = self.class.post('/v1/embeddings',
                                  headers: {
                                    'Content-Type'  => 'application/json',
                                    'Authorization' => "Bearer #{@options[:api_key]}",
                                  },
                                  body:    {
-                                   model:           @options[:embedding_model],
+                                   model:           embedding_model,
                                    input:           clean_text_input,
                                    encoding_format: 'float',
                                  }.to_json)
@@ -43,10 +44,10 @@ class Prescient::Provider::OpenAI < Prescient::Base
       embedding_data = response.parsed_response.dig('data', 0, 'embedding')
       raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding_data
 
-      expected_dimensions = EMBEDDING_DIMENSIONS[@options[:embedding_model]] || @options[:embedding_dimensions]
+      expected_dimensions = EMBEDDING_DIMENSIONS[embedding_model] || @options[:embedding_dimensions]
       unless expected_dimensions
         raise Prescient::Error,
-              "Embedding dimensions are required for model #{@options[:embedding_model]}"
+              "Embedding dimensions are required for model #{embedding_model}"
       end
 
       validate_embedding_dimensions(embedding_data, expected_dimensions)
@@ -67,7 +68,7 @@ class Prescient::Provider::OpenAI < Prescient::Base
                                    'Authorization' => "Bearer #{@options[:api_key]}",
                                  },
                                  body:    {
-                                   model:       @options[:chat_model],
+                                   model:       options[:model] || @options[:chat_model],
                                    messages:    [
                                      {
                                        role:    'user',
@@ -86,7 +87,7 @@ class Prescient::Provider::OpenAI < Prescient::Base
 
       {
         response:        content.strip,
-        model:           @options[:chat_model],
+        model:           options[:model] || @options[:chat_model],
         provider:        'openai',
         processing_time: nil,
         metadata:        {

data/lib/prescient/version.rb

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

data/lib/prescient.rb

@@ -9,6 +9,7 @@ require_relative 'prescient/provider/anthropic'
 require_relative 'prescient/provider/openai'
 require_relative 'prescient/provider/huggingface'
 require_relative 'prescient/client'
+require_relative 'prescient/cli'
 
 # Main Prescient module for AI provider abstraction
 #

data/sig/prescient.rbs

@@ -193,7 +193,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 +203,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 +211,21 @@ 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
+
   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.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]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prescient
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.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,8 +56,10 @@ 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/errors.rb
 - lib/prescient/pgvector.rb