Module: Prescient

Defined in:
lib/prescient.rb,
lib/prescient/api.rb,
lib/prescient/cli.rb,
lib/prescient/base.rb,
lib/prescient/tool.rb,
lib/prescient/agent.rb,
lib/prescient/client.rb,
lib/prescient/errors.rb,
lib/prescient/version.rb,
lib/prescient/pgvector.rb,
lib/prescient/agent/errors.rb,
lib/prescient/provider/xai.rb,
lib/prescient/tool/searxng.rb,
lib/prescient/document_source.rb,
lib/prescient/provider/gemini.rb,
lib/prescient/provider/ollama.rb,
lib/prescient/provider/openai.rb,
lib/prescient/tool/search_api.rb,
lib/prescient/provider/mistral.rb,
lib/prescient/provider/deepseek.rb,
lib/prescient/provider/anthropic.rb,
lib/prescient/configuration_loader.rb,
lib/prescient/provider/huggingface.rb

Overview

Main Prescient module for AI provider abstraction

Defined Under Namespace

Modules: Agent, DocumentSource, MCP, 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.8.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



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

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:



67
68
69
 
# File 'lib/prescient.rb', line 67

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:



60
61
62
 
# File 'lib/prescient.rb', line 60

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



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

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



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

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



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

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:



94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/prescient.rb', line 94

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:



81
82
83
 
# File 'lib/prescient.rb', line 81

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:



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

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:



74
75
76
 
# File 'lib/prescient.rb', line 74

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