Module: Prescient

Defined in:
lib/prescient.rb,
lib/prescient/client.rb,
lib/prescient/errors.rb,
lib/prescient/version.rb

Overview

Main Prescient module for AI provider abstraction

Prescient provides a unified interface for working with multiple AI providers including Ollama, OpenAI, Anthropic, and Hugging Face. It supports both embedding generation and text completion with configurable context handling.

Examples:

Basic usage

Prescient.configure do |config|
  config.add_provider(:openai, Prescient::Provider::OpenAI,
                      api_key: 'your-api-key')
end

client = Prescient.client(:openai)
response = client.generate_response("Hello, world!")

Embedding generation

embedding = client.generate_embedding("Some text to embed")
puts embedding.length # => 1536 (for OpenAI text-embedding-3-small)

Defined Under Namespace

Modules: Pgvector, Provider, Tool Classes: API, AuthenticationError, Base, CLI, Client, Configuration, ConfigurationLoader, ConnectionError, Error, InvalidResponseError, InvalidVectorError, ModelNotAvailableError, ProviderError, RateLimitError, ToolConfigurationError, ToolConnectionError, ToolError, ToolInvalidResponseError

Constant Summary collapse

VERSION =

Current Prescient gem version.

'0.7.0'

Class Method Summary collapse

Class Method Details

.client(provider_name = nil, enable_fallback: true, provider_options: {}) ⇒ Client

Convenience methods for quick access

Parameters:

  • provider_name (Symbol, nil) (defaults to: nil) —

    Provider to use, or the configured default

  • enable_fallback (Boolean) (defaults to: true) —

    Whether provider fallback is enabled

  • provider_options (Hash) (defaults to: {}) —

    Temporary options for the selected provider

Returns:

  • (Client) —

    A configured client instance



224
225
226
 
# File 'lib/prescient/client.rb', line 224

def self.client(provider_name = nil, enable_fallback: true, provider_options: {})
  Client.new(provider_name, enable_fallback: enable_fallback, provider_options: provider_options)
end

.configuration ⇒ Configuration

Get the current configuration instance

Returns:



62
63
64
 
# File 'lib/prescient.rb', line 62

def self.configuration
  @_configuration ||= Configuration.new
end

.configure {|config| ... } ⇒ void

This method returns an undefined value.

Configure Prescient with custom settings and providers

Examples:

Configure with custom provider

Prescient.configure do |config|
  config.default_provider = :openai
  config.timeout = 60
  config.add_provider(:openai, Prescient::Provider::OpenAI,
                      api_key: 'your-key')
end

Yields:

  • (config) —

    Configuration block

Yield Parameters:



55
56
57
 
# File 'lib/prescient.rb', line 55

def self.configure
  yield(configuration)
end

.generate_embedding(text, provider: nil, enable_fallback: true, **options) ⇒ Array<Float>

Generate an embedding through a configured provider.

Parameters:

  • text (String) —

    Text to embed

  • provider (Symbol, nil) (defaults to: nil) —

    Provider to use

  • enable_fallback (Boolean) (defaults to: true) —

    Whether provider fallback is enabled

Returns:

  • (Array<Float>) —

    Embedding vector



234
235
236
 
# File 'lib/prescient/client.rb', line 234

def self.generate_embedding(text, provider: nil, enable_fallback: true, **options)
  client(provider, enable_fallback: enable_fallback).generate_embedding(text, **options)
end

.generate_response(prompt, context_items = [], provider: nil, enable_fallback: true, **options) ⇒ Hash

Generate a response through a configured provider.

Parameters:

  • prompt (String) —

    Prompt to send

  • context_items (Array<Hash, String>) (defaults to: []) —

    Optional context items

  • provider (Symbol, nil) (defaults to: nil) —

    Provider to use

  • enable_fallback (Boolean) (defaults to: true) —

    Whether provider fallback is enabled

Returns:

  • (Hash) —

    Normalized provider response with :response, :model, :provider and optional metadata



246
247
248
 
# File 'lib/prescient/client.rb', line 246

def self.generate_response(prompt, context_items = [], provider: nil, enable_fallback: true, **options)
  client(provider, enable_fallback: enable_fallback).generate_response(prompt, context_items, **options)
end

.health_check(provider: nil) ⇒ Hash

Return the health status of a configured provider.

Parameters:

  • provider (Symbol, nil) (defaults to: nil) —

    Provider to check

Returns:

  • (Hash) —

    Provider health information



280
281
282
 
# File 'lib/prescient/client.rb', line 280

def self.health_check(provider: nil)
  client(provider, enable_fallback: false).health_check
end

.load_configuration(path = nil, env: ENV) ⇒ Configuration

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.

Parameters:

  • path (String, nil) (defaults to: nil) —

    YAML configuration file path

  • env (Hash) (defaults to: ENV) —

    Environment variables used while loading configuration

Returns:



89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/prescient.rb', line 89

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)
                      configure_default_tools(config, env)
                    end
                  end

  @_configuration = configuration
end

.reset_configuration! ⇒ Configuration

Reset configuration to defaults

Returns:



76
77
78
 
# File 'lib/prescient.rb', line 76

def self.reset_configuration!
  @_configuration = Configuration.new
end

.search_and_generate(query, tool: :web_search, provider: nil, limit: nil, enable_fallback: true, provider_options: {}, **options) ⇒ Hash

Search with an explicit external tool and optionally use the normalized results as context for a configured AI provider.

Parameters:

  • query (String) —

    Search query and generation prompt

  • tool (Symbol, String) (defaults to: :web_search) —

    Configured external tool name

  • provider (Symbol, nil) (defaults to: nil) —

    Provider to use for generation

  • limit (Integer, nil) (defaults to: nil) —

    Maximum number of search results

  • enable_fallback (Boolean) (defaults to: true) —

    Whether provider fallback is enabled

  • provider_options (Hash) (defaults to: {}) —

    Temporary provider configuration overrides

Returns:

  • (Hash) —

    Normalized provider response

Raises:



260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/prescient/client.rb', line 260

def self.search_and_generate(query, tool: :web_search, provider: nil, limit: nil,
                             enable_fallback: true, provider_options: {}, **options)
  search_tool = self.tool(tool)
  raise Prescient::ToolConfigurationError, "tool not configured: #{tool}" unless search_tool

  search_result = search_tool.search(query, limit: limit)
  context_items = search_result[:results]
  raise Prescient::ToolInvalidResponseError, 'tool results must be an array' unless context_items.is_a?(Array)

  client(provider, enable_fallback:, provider_options:).generate_response(
    query,
    context_items,
    **options,
  )
end

.tool(name) ⇒ Prescient::Tool::Base?

Look up a configured external tool.

Parameters:

  • name (Symbol, String) —

    Tool name

Returns:



69
70
71
 
# File 'lib/prescient.rb', line 69

def self.tool(name)
  configuration.tool(name)
end