prescient 0.2.0 → 0.4.0

data/VECTOR_SEARCH_GUIDE.md

@@ -2,23 +2,46 @@
 
 This guide provides a comprehensive overview of using Prescient with PostgreSQL's pgvector extension for semantic search and similarity matching.
 
+The runnable companion is [`examples/vector_search.rb`](examples/vector_search.rb);
+see the [examples guide](examples/README.md) for setup and the [main README](README.md)
+for the provider API.
+
 ## Quick Start
 
+For a reusable embedding store, use the library boundary rather than copying
+the example's application-specific SQL:
+
+```ruby
+require 'prescient'
+require 'pg'
+
+store = Prescient::Pgvector::Store.new(
+  connection: PG.connect(dbname: 'my_app'),
+  dimensions: 1536,
+)
+store.install!
+store.create_index!(metric: :cosine)
+```
+
+`Store` owns only its `prescient_embeddings` table. It does not manage document
+or chunk tables, connections, migrations outside that table, or the `pg` gem.
+Use `#upsert` and `#search` with embeddings of exactly the configured dimension.
+
 ### 1. Start Services
 
 ```bash
 # Start PostgreSQL with pgvector and Ollama
-docker-compose up -d postgres ollama
+docker compose up -d postgres ollama
 
 # Wait for services to be ready
-docker-compose logs -f postgres ollama
+docker compose logs -f postgres ollama
 ```
 
 ### 2. Initialize Models
 
 ```bash
 # Pull required Ollama models
-docker-compose up ollama-init
+docker compose run --rm ollama-init
 
 # Or manually:
 ./scripts/setup-ollama-models.sh
@@ -117,7 +140,7 @@ vector_str = "[#{embedding.join(',')}]"
 
 db.exec_params(
   "INSERT INTO document_embeddings (document_id, embedding_provider, embedding_model, embedding_dimensions, embedding, embedding_text) VALUES ($1, $2, $3, $4, $5, $6)",
-  [document_id, 'ollama', 'nomic-embed-text', 768, vector_str, content]
+  [document_id, 'ollama', 'nomic-embed-text', embedding.length, vector_str, content]
 )
 ```
 
@@ -211,7 +234,7 @@ chunks.each do |chunk|
   # Store chunk embedding
   db.exec_params(
     "INSERT INTO chunk_embeddings (chunk_id, document_id, embedding_provider, embedding_model, embedding_dimensions, embedding) VALUES ($1, $2, $3, $4, $5, $6)",
-    [chunk_id, document_id, 'ollama', 'nomic-embed-text', 768, chunk_vector]
+    [chunk_id, document_id, 'ollama', 'nomic-embed-text', chunk_embedding.length, chunk_vector]
   )
 end
 ```
@@ -280,7 +303,7 @@ db.transaction do
     vector_str = "[#{embedding.join(',')}]"
     db.exec_params(
       "INSERT INTO document_embeddings (...) VALUES (...)",
-      [documents[index].id, 'ollama', 'nomic-embed-text', 768, vector_str, texts[index]]
+      [documents[index].id, 'ollama', 'nomic-embed-text', embedding.length, vector_str, texts[index]]
     )
   end
 end
@@ -322,14 +345,15 @@ Store embeddings from multiple providers for comparison:
 
 ```ruby
 providers = [
-  { client: Prescient.client(:ollama), name: 'ollama', model: 'nomic-embed-text', dims: 768 },
-  { client: Prescient.client(:openai), name: 'openai', model: 'text-embedding-3-small', dims: 1536 }
+  { client: Prescient.client(:ollama), name: 'ollama', model: 'nomic-embed-text' },
+  { client: Prescient.client(:openai), name: 'openai', model: 'text-embedding-3-small' }
 ]
 
 providers.each do |provider|
   next unless provider[:client].available?
 
   embedding = provider[:client].generate_embedding(text)
+  provider[:dims] = embedding.length
   vector_str = "[#{embedding.join(',')}]"
 
   db.exec_params(

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/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/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