prescient 0.2.0 → 0.3.0

data/docker-compose.yml

@@ -1,8 +1,6 @@
 # Docker Compose configuration for running Ollama with Prescient gem
 # This provides a local AI environment for development and testing
 
-version: '3.8'
-
 services:
   ollama:
     image: ollama/ollama:latest
@@ -65,7 +63,7 @@ services:
         # Pull chat model  
         curl -X POST http://ollama:11434/api/pull \
           -H "Content-Type: application/json" \
-          -d "{\"name\": \"llama3.1:8b\"}"
+          -d "{\"name\": \"llama3.2:3b\"}"
         
         echo "Models pulled successfully!"
       '
@@ -122,7 +120,7 @@ services:
       # Ollama configuration
       - OLLAMA_URL=http://ollama:11434
       - OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-      - OLLAMA_CHAT_MODEL=llama3.1:8b
+      - OLLAMA_CHAT_MODEL=llama3.2:3b
       
       # Optional: Other AI provider configurations
       - OPENAI_API_KEY=${OPENAI_API_KEY:-}
@@ -150,4 +148,4 @@ volumes:
 
 networks:
   default:
-    name: prescient-network
+    name: prescient-network

data/examples/README.md

@@ -0,0 +1,45 @@
+# Prescient examples
+
+These scripts demonstrate the supported public API. They use the local
+library checkout, so run them from the repository root after installing the
+development dependencies:
+
+```bash
+bundle install
+```
+
+## Examples
+
+- `basic_usage.rb` — default-provider generation, embeddings, health checks,
+  provider selection, and custom configuration.
+- `custom_prompts.rb` — system prompts and no-context/with-context templates.
+- `custom_contexts.rb` — explicit context types, field matching, formatting,
+  and embedding field selection.
+- `vector_search.rb` — PostgreSQL/pgvector storage and similarity search.
+
+The first three examples use Ollama by default. Start Ollama and pull the
+current local models before running them:
+
+```bash
+docker compose up -d ollama
+docker compose run --rm ollama-init
+bundle exec ruby examples/basic_usage.rb
+```
+
+The vector-search example additionally requires PostgreSQL with pgvector:
+
+```bash
+docker compose up -d postgres ollama
+docker compose run --rm ollama-init
+DB_HOST=localhost bundle exec ruby examples/vector_search.rb
+```
+
+Cloud-provider examples require the corresponding credentials and provider
+configuration. The scripts are demonstrations rather than isolated test
+fixtures; they may make real provider requests when the configured service is
+available.
+
+See the [main README](../README.md) for configuration, fallback behavior,
+prompt templates, context exclusions, embeddings, and the public API. Rails
+applications can also use the [integration guide](../INTEGRATION_GUIDE.md),
+and PostgreSQL users should read the [pgvector guide](../VECTOR_SEARCH_GUIDE.md).

data/examples/basic_usage.rb

@@ -110,7 +110,7 @@ Prescient.configure do |config|
   config.add_provider(:custom_ollama, Prescient::Provider::Ollama,
     url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b',
+    chat_model: 'llama3.2:3b',
     timeout: 60
   )
 end
@@ -120,4 +120,4 @@ puts "   Timeout: #{Prescient.configuration.timeout}s"
 puts "   Retry attempts: #{Prescient.configuration.retry_attempts}"
 puts "   Providers: #{Prescient.configuration.providers.keys.join(', ')}"
 
-puts "\n🎉 Examples completed!"
+puts "\n🎉 Examples completed!"

data/examples/custom_contexts.rb

@@ -16,7 +16,7 @@ Prescient.configure do |config|
   config.add_provider(:ecommerce, Prescient::Provider::Ollama,
     url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b',
+    chat_model: 'llama3.2:3b',
     # Define your own context types - no hardcoded assumptions!
     context_configs: {
       'product' => {
@@ -88,7 +88,7 @@ Prescient.configure do |config|
   config.add_provider(:healthcare, Prescient::Provider::Ollama,
     url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b',
+    chat_model: 'llama3.2:3b',
     context_configs: {
       'patient' => {
         fields: %w[name age gender medical_conditions medications],
@@ -158,7 +158,7 @@ Prescient.configure do |config|
   config.add_provider(:project_mgmt, Prescient::Provider::Ollama,
     url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b',
+    chat_model: 'llama3.2:3b',
     context_configs: {
       'issue' => {
         fields: %w[title description status priority assignee labels created_date],
@@ -237,7 +237,7 @@ begin
     config.add_provider(:embedding_demo, Prescient::Provider::Ollama,
       url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
       embedding_model: 'nomic-embed-text',
-      chat_model: 'llama3.1:8b',
+      chat_model: 'llama3.2:3b',
       context_configs: {
         'blog_post' => {
           fields: %w[title content author tags category publish_date],
@@ -288,7 +288,7 @@ Prescient.configure do |config|
   config.add_provider(:no_config, Prescient::Provider::Ollama,
     url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b'
+    chat_model: 'llama3.2:3b'
     # No context_configs defined - uses pure default behavior
   )
 end
@@ -352,4 +352,4 @@ puts "\n🎯 Best Practices:"
 puts "   - Define context_configs for your specific domain"
 puts "   - Use explicit 'type' field when context detection isn't reliable"
 puts "   - Exclude sensitive/metadata fields from embedding_fields"
-puts "   - Test with and without context configs to see the difference"
+puts "   - Test with and without context configs to see the difference"

data/examples/custom_prompts.rb

@@ -15,7 +15,7 @@ Prescient.configure do |config|
   config.add_provider(:customer_service, Prescient::Provider::Ollama,
     url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b',
+    chat_model: 'llama3.2:3b',
     prompt_templates: {
       system_prompt: 'You are a friendly customer service representative. Be helpful, empathetic, and professional.',
       no_context_template: <<~TEMPLATE.strip,
@@ -73,7 +73,7 @@ Prescient.configure do |config|
   config.add_provider(:tech_docs, Prescient::Provider::Ollama,
     url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b',
+    chat_model: 'llama3.2:3b',
     prompt_templates: {
       system_prompt: 'You are a technical documentation assistant. Provide clear, accurate, and detailed technical explanations with code examples when relevant.',
       no_context_template: <<~TEMPLATE.strip,
@@ -125,7 +125,7 @@ Prescient.configure do |config|
   config.add_provider(:creative, Prescient::Provider::Ollama,
     url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b',
+    chat_model: 'llama3.2:3b',
     prompt_templates: {
       system_prompt: 'You are a creative writing assistant. Help with storytelling, character development, and creative inspiration. Be imaginative and encouraging.',
       no_context_template: <<~TEMPLATE.strip,
@@ -182,7 +182,7 @@ Prescient.configure do |config|
   config.add_provider(:custom_default, Prescient::Provider::Ollama,
     url: ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b',
+    chat_model: 'llama3.2:3b',
     prompt_templates: {
       # Only override the system prompt, keep default templates
       system_prompt: 'You are Sherlock Holmes. Approach every question with deductive reasoning and attention to detail.'
@@ -209,4 +209,4 @@ puts "\n💡 Tips:"
 puts "   - Use %{system_prompt}, %{query}, and %{context} placeholders in templates"
 puts "   - Templates use Ruby's % string formatting"
 puts "   - Override any or all template parts (system_prompt, no_context_template, with_context_template)"
-puts "   - Each provider can have completely different prompt behavior"
+puts "   - Each provider can have completely different prompt behavior"

data/examples/vector_search.rb

@@ -31,7 +31,7 @@ class VectorSearchExample
     
     # Check if services are available
     unless check_services_available
-      puts "❌ Required services not available. Please start with: docker-compose up -d"
+      puts "❌ Required services not available. Please start with: docker compose up -d"
       return
     end
 
@@ -327,4 +327,4 @@ puts "   - Try different embedding models (OpenAI, HuggingFace)"
 puts "   - Implement hybrid search (vector + keyword)"
 puts "   - Add document chunking for large texts"
 puts "   - Experiment with different similarity thresholds"
-puts "   - Add result re-ranking and filtering"
+puts "   - Add result re-ranking and filtering"

data/lib/prescient/base.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'net/http'
+
 # Base class for all AI provider implementations
 #
 # This abstract base class defines the common interface that all AI providers
@@ -7,7 +10,8 @@
 # formatting, prompt building, and error handling.
 #
 # @abstract Subclass and implement {#generate_embedding}, {#generate_response},
-#   {#health_check}, and {#validate_configuration!}
+#   {#health_check}, and any configuration validation required by
+#   {#validate_configuration!}
 #
 # @example Creating a custom provider
 #   class MyProvider < Prescient::Base
@@ -24,11 +28,9 @@
 #     end
 #   end
 #
-# @author Claude Code
-# @since 1.0.0
 class Prescient::Base
   # @return [Hash] Configuration options for this provider instance
-  attr_reader :options
+  attr_reader :options, :provider_name
 
   # Initialize the provider with configuration options
   #
@@ -38,8 +40,12 @@ class Prescient::Base
   # @option options [Integer] :timeout Request timeout in seconds
   # @option options [Hash] :prompt_templates Custom prompt templates
   # @option options [Hash] :context_configs Context formatting configurations
+  # @option options [Integer] :embedding_dimensions Expected custom embedding size
+  # @option options [Array<Symbol, String>] :context_excluded_fields Additional
+  #   field names excluded from generic embedding text
   def initialize(**options)
     @options = options
+    @provider_name = options.fetch(:provider_name, self.class.to_s.split('::').last).to_s.sub(/\A./, &:upcase)
     validate_configuration!
   end
 
@@ -80,7 +86,8 @@ class Prescient::Base
   # This method must be implemented by subclasses to provide health check
   # functionality.
   #
-  # @return [Hash] Health status with :status, :provider keys and optional details
+  # @return [Hash] Health status with at least :status and :provider keys,
+  #   and typically :reachable and :ready for modern adapters
   # @raise [NotImplementedError] If not implemented by subclass
   # @abstract
   def health_check
@@ -89,9 +96,14 @@ class Prescient::Base
 
   # Check if the provider is currently available
   #
-  # @return [Boolean] true if provider is healthy and available
+  # Returns `true` when the health check reports `reachable: true`.
+  # For legacy adapters that only return a status string, `status == "healthy"`
+  # is also treated as available.
+  #
+  # @return [Boolean] true if the provider is currently reachable
   def available?
-    health_check[:status] == 'healthy'
+    health = health_check
+    health.key?(:reachable) ? health[:reachable] == true : health[:status] == 'healthy'
   rescue StandardError
     false
   end
@@ -135,25 +147,29 @@ class Prescient::Base
     raise Prescient::Error, "Unexpected error: #{e.message}"
   end
 
-  # Normalize embedding dimensions to match expected size
+  # Validate embedding dimensions against the configured model dimension.
   #
-  # Ensures embedding vectors have consistent dimensions by truncating
-  # longer vectors or padding shorter ones with zeros.
+  # Embedding dimensions are part of the vector-storage contract. Vectors are
+  # never padded or truncated because either operation changes their meaning.
   #
-  # @param embedding [Array<Float>] The embedding vector to normalize
-  # @param target_dimensions [Integer] The desired number of dimensions
-  # @return [Array<Float>, nil] Normalized embedding or nil if input invalid
-  def normalize_embedding(embedding, target_dimensions)
-    return nil unless embedding.is_a?(Array)
-    return embedding.first(target_dimensions) if embedding.length >= target_dimensions
-
-    embedding + Array.new(target_dimensions - embedding.length, 0.0)
+  # @param embedding [Array<Float>] The embedding vector to validate
+  # @param target_dimensions [Integer] The required number of dimensions
+  # @return [Array<Float>] The original embedding when dimensions are valid
+  # @raise [Prescient::InvalidResponseError] If the vector is malformed or has
+  #   an unexpected dimension
+  def validate_embedding_dimensions(embedding, target_dimensions)
+    raise Prescient::InvalidResponseError, 'Embedding response is not an array' unless embedding.is_a?(Array)
+
+    return embedding if embedding.length == target_dimensions
+
+    raise Prescient::InvalidResponseError,
+          "Invalid embedding dimensions: expected #{target_dimensions}, got #{embedding.length}"
   end
 
   # Clean and preprocess text for AI processing
   #
-  # Removes excess whitespace, normalizes spacing, and enforces length
-  # limits suitable for most AI models.
+  # Removes excess whitespace, normalizes spacing, and truncates to the
+  # library's current 8,000-character input ceiling.
   #
   # @param text [String, nil] The text to clean
   # @return [String] Cleaned text, empty string if input was nil/empty
@@ -224,12 +240,15 @@ class Prescient::Base
 
   # Minimal default context configuration - users should define their own contexts
   def default_context_configs
+    embedding_fields = [] # : Array[untyped]
+    fields = [] # : Array[untyped]
+
     {
       # Generic fallback configuration - works with any hash structure
       'default' => {
-        fields:           [], # Will be dynamically determined from item keys
+        fields:           fields, # Will be dynamically determined from item keys
         format:           nil, # Will use fallback formatting
-        embedding_fields: [], # Will use all string/text fields
+        embedding_fields: embedding_fields, # Will use all string/text fields
       },
     }
   end
@@ -245,9 +264,13 @@ class Prescient::Base
 
   # Extract text values from hash, excluding non-textual fields
   def extract_text_values(item)
-    # Common fields to exclude from embedding text
-    # TODO: configurable fields to exclude aside from the common ones below
-    exclude_fields = ['id', '_id', 'uuid', 'created_at', 'updated_at', 'timestamp', 'version', 'status', 'active']
+    # Common fields to exclude from embedding text. Provider-specific fields can
+    # be added with the :context_excluded_fields option.
+    default_excluded_fields = ['id', '_id', 'uuid', 'created_at', 'updated_at', 'timestamp', 'version', 'status',
+                               'active']
+    configured_fields = Array(@options[:context_excluded_fields]) # : Array[untyped]
+    configured_excluded_fields = configured_fields.map { |field| field.to_s.downcase }
+    exclude_fields = default_excluded_fields | configured_excluded_fields
 
     item.filter_map { |key, value|
       next if exclude_fields.include?(key.to_s.downcase)
@@ -298,7 +321,7 @@ class Prescient::Base
 
   # Build format data from item fields
   def build_format_data(item, config)
-    format_data = {}
+    format_data = {} # : Hash[Symbol, untyped]
     fields_to_check = config[:fields].any? ? config[:fields] : item.keys.map(&:to_s)
 
     fields_to_check.each do |field|
@@ -371,4 +394,36 @@ class Prescient::Base
     # Fallback: join key-value pairs
     (format_data || item).map { |k, v| "#{k}: #{v}" }.join(', ')
   end
+
+  def validate_response!(response, operation)
+    return if response.success?
+
+    resp_message, error_class = case response.code
+                                when 400
+                                  ['Bad Request', Prescient::Error]
+                                when 401
+                                  ['Authentication Failure', Prescient::AuthenticationError]
+                                when 403
+                                  ['Forbidden Access', Prescient::AuthenticationError]
+                                when 404
+                                  ['Model Not Available', Prescient::ModelNotAvailableError]
+                                when 429
+                                  ['Rate Limit Exceeded', Prescient::RateLimitError]
+                                when 500..599
+                                  ["#{provider_name} Server Error", Prescient::ProviderError]
+                                else
+                                  ["#{provider_name} Request Failure", Prescient::Error]
+                                end
+
+    raise provider_error(resp_message, response, error_class:, operation:)
+  end
+
+  def provider_error(message, response, operation:, provider: nil, error_class: Prescient::ProviderError)
+    error_class.new(
+      message,
+      provider:  provider || provider_name,
+      operation:,
+      status:    response.code,
+    )
+  end
 end

data/lib/prescient/client.rb

@@ -16,13 +16,11 @@ module Prescient
   #   client = Prescient::Client.new  # Uses configured default
   #   puts client.provider_name       # => :ollama (or configured default)
   #
-  # @author Claude Code
-  # @since 1.0.0
   class Client
     # @return [Symbol] The name of the provider being used
     attr_reader :provider_name
 
-    # @return [Base] The underlying provider instance
+    # @return [Prescient::Base] The underlying provider instance
     attr_reader :provider
 
     # Initialize a new client with the specified provider
@@ -35,7 +33,7 @@ module Prescient
       @provider = Prescient.configuration.provider(@provider_name)
       @enable_fallback = enable_fallback
 
-      raise Prescient::Error, "Provider not found: #{@provider_name}" unless @provider
+      raise Prescient::Error, "Provider not configured: #{@provider_name}" unless @provider
     end
 
     # Generate embeddings for the given text
@@ -84,14 +82,14 @@ module Prescient
 
     # Check the health status of the provider
     #
-    # @return [Hash] Health status information
+    # @return [Hash] Health status information from the selected provider
     def health_check
       @provider.health_check
     end
 
     # Check if the provider is currently available
     #
-    # @return [Boolean] true if provider is healthy and available
+    # @return [Boolean] true if the provider currently passes its availability check
     def available?
       @provider.available?
     end
@@ -101,7 +99,8 @@ module Prescient
     # Returns details about the provider including its availability
     # and configuration options (with sensitive data removed).
     #
-    # @return [Hash] Provider information including :name, :class, :available, :options
+    # @return [Hash] Provider information including :name, :class, :available,
+    #   and recursively sanitized :options
     def provider_info
       {
         name:      @provider_name,
@@ -111,20 +110,25 @@ module Prescient
       }
     end
 
-    def method_missing(method_name, ...)
-      @provider.respond_to?(method_name) ? @provider.send(method_name, ...) : super
-    end
-
-    def respond_to_missing?(method_name, include_private = false)
-      @provider.respond_to?(method_name, include_private) || super
-    end
-
     private
 
-    # TODO: configurable keys to sanitize
     def sanitize_options(options)
-      sensitive_keys = [:api_key, :password, :token, :secret]
-      options.reject { |key, _| sensitive_keys.include?(key.to_sym) }
+      sensitive_keys = Prescient::Configuration::DEFAULT_SENSITIVE_KEYS + Prescient.configuration.sensitive_keys
+
+      case options
+      when Hash
+        sanitized = {} # : Hash[untyped, untyped]
+        options.each do |key, value|
+          next if key.respond_to?(:to_sym) && sensitive_keys.include?(key.to_sym)
+
+          sanitized[key] = sanitize_options(value)
+        end
+        sanitized
+      when Array
+        options.map { |value| sanitize_options(value) }
+      else
+        options
+      end
     end
 
     def with_error_handling
@@ -150,24 +154,17 @@ module Prescient
       last_error = nil
 
       providers_to_try.each_with_index do |provider_name, index|
-        # Use existing provider instance for primary provider, create new ones for fallbacks
-        provider = if index.zero? && provider_name == @provider_name
-                     @provider
-                   else
-                     Prescient.configuration.provider(provider_name)
-                   end
+        provider = provider_for(provider_name, index)
         next unless provider
 
-        # Check if provider is available before trying
-        next unless provider.available?
-
-        # Use retry logic for each provider
+        # Use the provider operation as the availability probe.
         return with_error_handling do
           provider.send(method_name, *args, **options)
         end
       rescue Prescient::Error => e
+        raise e unless fallback_eligible?(e)
+
         last_error = e
-        # Log the error and continue to next provider
         next
       end
 
@@ -175,36 +172,73 @@ module Prescient
       raise last_error || Prescient::Error.new("No available providers for #{method_name}")
     end
 
+    def provider_for(provider_name, index)
+      return @provider if index.zero? && provider_name == @provider_name
+
+      Prescient.configuration.provider(provider_name)
+    end
+
     def providers_to_try
       providers = [@provider_name]
 
       # Add configured fallback providers
       fallback_providers = Prescient.configuration.fallback_providers
-      if fallback_providers && !fallback_providers.empty?
-        providers += fallback_providers.reject { |p| p == @provider_name }
-      else
-        # If no explicit fallbacks configured, try all available providers
-        available = Prescient.configuration.available_providers
-        providers += available.reject { |p| p == @provider_name }
-      end
+      additional_providers = if fallback_providers && !fallback_providers.empty?
+                               fallback_providers.reject { |p| p == @provider_name }
+                             else
+                               # If no explicit fallbacks are configured, probe all configured providers
+                               Prescient.configuration.providers.keys.reject { |p| p == @provider_name }
+                             end
+      providers += additional_providers
 
       providers.uniq
     end
+
+    def fallback_eligible?(error)
+      [
+        Prescient::ConnectionError,
+        Prescient::RateLimitError,
+        Prescient::ModelNotAvailableError,
+        Prescient::ProviderError,
+      ].any? { |error_class| error.is_a?(error_class) }
+    end
   end
 
   # Convenience methods for quick access
+  #
+  # @param provider_name [Symbol, nil] Provider to use, or the configured default
+  # @param enable_fallback [Boolean] Whether provider fallback is enabled
+  # @return [Client] A configured client instance
   def self.client(provider_name = nil, enable_fallback: true)
     Client.new(provider_name, enable_fallback: enable_fallback)
   end
 
+  # Generate an embedding through a configured provider.
+  #
+  # @param text [String] Text to embed
+  # @param provider [Symbol, nil] Provider to use
+  # @param enable_fallback [Boolean] Whether provider fallback is enabled
+  # @return [Array<Float>] Embedding vector
   def self.generate_embedding(text, provider: nil, enable_fallback: true, **options)
     client(provider, enable_fallback: enable_fallback).generate_embedding(text, **options)
   end
 
+  # Generate a response through a configured provider.
+  #
+  # @param prompt [String] Prompt to send
+  # @param context_items [Array<Hash, String>] Optional context items
+  # @param provider [Symbol, nil] Provider to use
+  # @param enable_fallback [Boolean] Whether provider fallback is enabled
+  # @return [Hash] Normalized provider response with :response, :model, :provider
+  #   and optional metadata
   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
 
+  # Return the health status of a configured provider.
+  #
+  # @param provider [Symbol, nil] Provider to check
+  # @return [Hash] Provider health information
   def self.health_check(provider: nil)
     client(provider, enable_fallback: false).health_check
   end

data/lib/prescient/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Prescient
+  # Base error class for all Prescient-specific errors
+  class Error < StandardError
+    attr_reader :provider
+    attr_reader :operation
+    attr_reader :status
+
+    def initialize(message = nil, provider: nil, operation: nil, status: nil)
+      super(message)
+
+      @provider = provider
+      @operation = operation
+      @status = status
+    end
+  end
+
+  # Raised when there are connection issues with AI providers
+  class ConnectionError < Error; end
+
+  # Raised when API authentication fails
+  class AuthenticationError < Error; end
+
+  # Raised when API rate limits are exceeded
+  class RateLimitError < Error; end
+
+  # Raised when a requested model is not available
+  class ModelNotAvailableError < Error; end
+
+  # Raised when AI provider returns invalid or malformed responses
+  class InvalidResponseError < Error; end
+
+  # Raised when a vector cannot be stored or searched safely
+  class InvalidVectorError < Error; end
+
+  # Raised when an AI provider reports a transient service-side failure
+  class ProviderError < Error; end
+
+  # Container module for AI provider implementations
+  #
+  # All provider classes should be defined within this module and inherit
+  # from {Prescient::Base}.
+  module Provider
+    # Module for AI provider implementations
+  end
+
+  # Namespace for optional PostgreSQL pgvector integration
+  module Pgvector
+  end
+end