prescient 0.0.0 → 0.2.0

data/db/init/03_create_indexes.sql

@@ -0,0 +1,96 @@
+-- Create vector similarity indexes for optimal search performance
+-- These indexes are crucial for fast similarity search with large datasets
+
+-- Vector indexes for document embeddings
+-- Using HNSW (Hierarchical Navigable Small World) for approximate nearest neighbor search
+-- Different distance functions: L2 distance (<->), inner product (<#>), cosine distance (<=>)
+
+-- Index for L2 distance (Euclidean) - good general purpose
+CREATE INDEX IF NOT EXISTS idx_document_embeddings_l2 
+ON document_embeddings 
+USING hnsw (embedding vector_l2_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- Index for cosine distance - good for normalized embeddings
+CREATE INDEX IF NOT EXISTS idx_document_embeddings_cosine 
+ON document_embeddings 
+USING hnsw (embedding vector_cosine_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- Index for inner product - good for some specific use cases
+CREATE INDEX IF NOT EXISTS idx_document_embeddings_ip 
+ON document_embeddings 
+USING hnsw (embedding vector_ip_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- Vector indexes for chunk embeddings (same pattern)
+CREATE INDEX IF NOT EXISTS idx_chunk_embeddings_l2 
+ON chunk_embeddings 
+USING hnsw (embedding vector_l2_ops)
+WITH (m = 16, ef_construction = 64);
+
+CREATE INDEX IF NOT EXISTS idx_chunk_embeddings_cosine 
+ON chunk_embeddings 
+USING hnsw (embedding vector_cosine_ops)
+WITH (m = 16, ef_construction = 64);
+
+CREATE INDEX IF NOT EXISTS idx_chunk_embeddings_ip 
+ON chunk_embeddings 
+USING hnsw (embedding vector_ip_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- Vector indexes for search queries
+CREATE INDEX IF NOT EXISTS idx_search_queries_l2 
+ON search_queries 
+USING hnsw (query_embedding vector_l2_ops)
+WITH (m = 16, ef_construction = 64);
+
+CREATE INDEX IF NOT EXISTS idx_search_queries_cosine 
+ON search_queries 
+USING hnsw (query_embedding vector_cosine_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- Composite indexes for common query patterns
+CREATE INDEX IF NOT EXISTS idx_document_embeddings_provider_dimensions_l2
+ON document_embeddings 
+USING hnsw (embedding vector_l2_ops)
+INCLUDE (embedding_provider, embedding_model, embedding_dimensions)
+WITH (m = 16, ef_construction = 64);
+
+CREATE INDEX IF NOT EXISTS idx_chunk_embeddings_document_cosine
+ON chunk_embeddings 
+USING hnsw (embedding vector_cosine_ops)
+INCLUDE (document_id, embedding_provider, embedding_model)
+WITH (m = 16, ef_construction = 64);
+
+-- Partial indexes for specific providers (more efficient if you mainly use one provider)
+-- Uncomment and modify these based on your primary use case:
+
+-- CREATE INDEX IF NOT EXISTS idx_document_embeddings_ollama_cosine
+-- ON document_embeddings 
+-- USING hnsw (embedding vector_cosine_ops)
+-- WITH (m = 16, ef_construction = 64)
+-- WHERE embedding_provider = 'ollama';
+
+-- CREATE INDEX IF NOT EXISTS idx_chunk_embeddings_openai_cosine
+-- ON chunk_embeddings 
+-- USING hnsw (embedding vector_cosine_ops)
+-- WITH (m = 16, ef_construction = 64)
+-- WHERE embedding_provider = 'openai';
+
+-- HNSW Index parameters explanation:
+-- m: maximum number of connections for each node (16 is good default)
+-- ef_construction: size of dynamic candidate list (64 is good default)
+-- Higher values = better accuracy but slower build time and more memory
+
+-- For very large datasets (millions of vectors), consider:
+-- m = 32, ef_construction = 128 for better accuracy
+-- m = 8, ef_construction = 32 for faster build/less memory
+
+-- Log successful index creation
+DO $$
+BEGIN
+    RAISE NOTICE 'Vector similarity indexes created successfully';
+    RAISE NOTICE 'Index parameters: m=16, ef_construction=64';
+    RAISE NOTICE 'Distance functions: L2, Cosine, Inner Product';
+END $$;

data/db/init/04_insert_sample_data.sql

@@ -0,0 +1,121 @@
+-- Insert sample data for testing and demonstration
+-- This provides realistic examples of how to structure data for vector search
+
+-- Insert sample documents
+INSERT INTO documents (title, content, source_type, source_url, metadata) VALUES
+    ('Ruby Programming Basics', 
+     'Ruby is a dynamic, open-source programming language with a focus on simplicity and productivity. It has an elegant syntax that is natural to read and easy to write. Ruby supports multiple programming paradigms, including procedural, object-oriented, and functional programming.',
+     'article', 
+     'https://example.com/ruby-basics',
+     '{"tags": ["programming", "ruby", "beginner"], "author": "Jane Doe", "difficulty": "beginner"}'::jsonb),
+     
+    ('Machine Learning with Python',
+     'Machine learning is a subset of artificial intelligence that enables computers to learn and make decisions from data without being explicitly programmed. Python has become the go-to language for machine learning due to its rich ecosystem of libraries like scikit-learn, TensorFlow, and PyTorch.',
+     'article',
+     'https://example.com/ml-python',
+     '{"tags": ["machine-learning", "python", "ai"], "author": "John Smith", "difficulty": "intermediate"}'::jsonb),
+     
+    ('Vector Databases Explained',
+     'Vector databases are specialized databases designed to store and query high-dimensional vectors. They are essential for similarity search, recommendation systems, and AI applications. Popular vector databases include Pinecone, Weaviate, and PostgreSQL with pgvector extension.',
+     'tutorial',
+     'https://example.com/vector-databases',
+     '{"tags": ["databases", "vectors", "similarity-search"], "author": "Alice Johnson", "difficulty": "advanced"}'::jsonb),
+     
+    ('API Design Best Practices',
+     'RESTful API design follows specific principles to create maintainable and scalable web services. Key principles include using HTTP methods correctly, designing intuitive URLs, handling errors gracefully, and providing clear documentation. Rate limiting and authentication are also crucial considerations.',
+     'guide',
+     'https://example.com/api-design',
+     '{"tags": ["api", "rest", "web-development"], "author": "Bob Wilson", "difficulty": "intermediate"}'::jsonb),
+     
+    ('Docker Container Security',
+     'Container security involves multiple layers of protection, from the host system to the container runtime and the applications themselves. Key practices include using minimal base images, scanning for vulnerabilities, implementing proper access controls, and monitoring container behavior in production.',
+     'security-guide',
+     'https://example.com/docker-security',
+     '{"tags": ["docker", "security", "containers"], "author": "Carol Brown", "difficulty": "advanced"}'::jsonb);
+
+-- Insert sample chunks for the longer documents
+-- Breaking documents into smaller chunks for better search granularity
+INSERT INTO document_chunks (document_id, chunk_index, chunk_text, chunk_metadata) VALUES
+    (1, 1, 'Ruby is a dynamic, open-source programming language with a focus on simplicity and productivity.', 
+     '{"start_pos": 0, "end_pos": 93, "word_count": 15}'::jsonb),
+    (1, 2, 'It has an elegant syntax that is natural to read and easy to write.',
+     '{"start_pos": 94, "end_pos": 161, "word_count": 13}'::jsonb),
+    (1, 3, 'Ruby supports multiple programming paradigms, including procedural, object-oriented, and functional programming.',
+     '{"start_pos": 162, "end_pos": 274, "word_count": 14}'::jsonb),
+     
+    (2, 1, 'Machine learning is a subset of artificial intelligence that enables computers to learn and make decisions from data without being explicitly programmed.',
+     '{"start_pos": 0, "end_pos": 147, "word_count": 23}'::jsonb),
+    (2, 2, 'Python has become the go-to language for machine learning due to its rich ecosystem of libraries like scikit-learn, TensorFlow, and PyTorch.',
+     '{"start_pos": 148, "end_pos": 285, "word_count": 22}'::jsonb),
+     
+    (3, 1, 'Vector databases are specialized databases designed to store and query high-dimensional vectors.',
+     '{"start_pos": 0, "end_pos": 95, "word_count": 14}'::jsonb),
+    (3, 2, 'They are essential for similarity search, recommendation systems, and AI applications.',
+     '{"start_pos": 96, "end_pos": 179, "word_count": 12}'::jsonb),
+    (3, 3, 'Popular vector databases include Pinecone, Weaviate, and PostgreSQL with pgvector extension.',
+     '{"start_pos": 180, "end_pos": 272, "word_count": 13}'::jsonb);
+
+-- Note: In a real application, you would generate embeddings using the Prescient gem
+-- and insert them into document_embeddings and chunk_embeddings tables.
+-- 
+-- Example workflow:
+-- 1. Insert document into documents table
+-- 2. Generate embedding using Prescient gem: 
+--    embedding = Prescient.generate_embedding(document.content)
+-- 3. Insert embedding into document_embeddings table
+-- 4. For large documents, split into chunks and generate embeddings for each chunk
+
+-- Insert sample search queries for demonstration
+INSERT INTO search_queries (query_text, embedding_provider, embedding_model, result_count, search_metadata) VALUES
+    ('How to learn Ruby programming?', 'ollama', 'nomic-embed-text', 3, 
+     '{"search_type": "semantic", "filters": {"difficulty": "beginner"}}'::jsonb),
+    ('Vector similarity search techniques', 'openai', 'text-embedding-3-small', 2,
+     '{"search_type": "semantic", "filters": {"tags": ["vectors", "databases"]}}'::jsonb),
+    ('Python machine learning libraries', 'ollama', 'nomic-embed-text', 5,
+     '{"search_type": "semantic", "filters": {"tags": ["python", "machine-learning"]}}'::jsonb);
+
+-- Create a view for easy querying of documents with their embeddings
+CREATE OR REPLACE VIEW documents_with_embeddings AS
+SELECT 
+    d.id,
+    d.title,
+    d.content,
+    d.source_type,
+    d.source_url,
+    d.metadata,
+    d.created_at,
+    de.embedding_provider,
+    de.embedding_model,
+    de.embedding_dimensions,
+    de.embedding,
+    de.embedding_text
+FROM documents d
+LEFT JOIN document_embeddings de ON d.id = de.document_id;
+
+-- Create a view for easy querying of chunks with their embeddings
+CREATE OR REPLACE VIEW chunks_with_embeddings AS
+SELECT 
+    dc.id as chunk_id,
+    dc.document_id,
+    dc.chunk_index,
+    dc.chunk_text,
+    dc.chunk_metadata,
+    d.title as document_title,
+    d.source_type,
+    ce.embedding_provider,
+    ce.embedding_model,
+    ce.embedding_dimensions,
+    ce.embedding
+FROM document_chunks dc
+JOIN documents d ON dc.document_id = d.id
+LEFT JOIN chunk_embeddings ce ON dc.id = ce.chunk_id
+ORDER BY dc.document_id, dc.chunk_index;
+
+-- Log successful sample data insertion
+DO $$
+BEGIN
+    RAISE NOTICE 'Sample data inserted successfully';
+    RAISE NOTICE 'Documents: %', (SELECT COUNT(*) FROM documents);
+    RAISE NOTICE 'Chunks: %', (SELECT COUNT(*) FROM document_chunks);
+    RAISE NOTICE 'Sample queries: %', (SELECT COUNT(*) FROM search_queries);
+END $$;

data/db/migrate/001_create_prescient_tables.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Rails migration for Prescient gem vector database tables
+# Copy this file to your Rails db/migrate directory and adjust the timestamp
+
+class CreatePrescientTables < ActiveRecord::Migration[7.0]
+  def up
+    # Enable pgvector extension
+    enable_extension 'vector'
+
+    # Documents table to store original content
+    create_table :documents do |t|
+      t.string :title, null: false, limit: 255
+      t.text :content, null: false
+      t.string :source_type, limit: 50 # e.g., 'pdf', 'webpage', 'text', 'api'
+      t.string :source_url, limit: 500
+      t.jsonb :metadata # Additional flexible metadata
+      t.timestamps
+    end
+
+    # Document embeddings table for vector search
+    create_table :document_embeddings do |t|
+      t.references :document, null: false, foreign_key: { on_delete: :cascade }
+      t.string :embedding_provider, null: false, limit: 50 # e.g., 'ollama', 'openai'
+      t.string :embedding_model, null: false, limit: 100 # e.g., 'nomic-embed-text'
+      t.integer :embedding_dimensions, null: false # e.g., 768, 1536, 384
+      t.vector :embedding, null: false # The actual vector embedding
+      t.text :embedding_text # The specific text that was embedded
+      t.timestamps
+    end
+
+    # Document chunks table for large documents split into smaller pieces
+    create_table :document_chunks do |t|
+      t.references :document, null: false, foreign_key: { on_delete: :cascade }
+      t.integer :chunk_index, null: false # Order of chunks within document
+      t.text :chunk_text, null: false
+      t.jsonb :chunk_metadata # Start/end positions, etc.
+      t.timestamps
+    end
+
+    # Chunk embeddings table for chunked document search
+    create_table :chunk_embeddings do |t|
+      t.references :chunk, null: false, foreign_key: { to_table: :document_chunks, on_delete: :cascade }
+      t.references :document, null: false, foreign_key: { on_delete: :cascade }
+      t.string :embedding_provider, null: false, limit: 50
+      t.string :embedding_model, null: false, limit: 100
+      t.integer :embedding_dimensions, null: false
+      t.vector :embedding, null: false
+      t.timestamps
+    end
+
+    # Search queries table to store user queries and results
+    create_table :search_queries do |t|
+      t.text :query_text, null: false
+      t.string :embedding_provider, null: false, limit: 50
+      t.string :embedding_model, null: false, limit: 100
+      t.vector :query_embedding
+      t.integer :result_count
+      t.jsonb :search_metadata # Search parameters, filters, etc.
+      t.timestamps
+    end
+
+    # Query results table to store search results for analysis
+    create_table :query_results do |t|
+      t.references :query, null: false, foreign_key: { to_table: :search_queries, on_delete: :cascade }
+      t.references :document, null: true, foreign_key: { on_delete: :cascade }
+      t.references :chunk, null: true, foreign_key: { to_table: :document_chunks, on_delete: :cascade }
+      t.float :similarity_score, null: false
+      t.integer :rank_position, null: false
+      t.timestamps
+    end
+
+    # Add indexes for better performance
+    add_index :documents, :source_type
+    add_index :documents, :created_at
+    add_index :documents, :metadata, using: :gin
+
+    add_index :document_embeddings, :document_id
+    add_index :document_embeddings, [:embedding_provider, :embedding_model], name: 'idx_doc_embeddings_provider_model'
+    add_index :document_embeddings, :embedding_dimensions
+
+    add_index :document_chunks, [:document_id, :chunk_index], unique: true
+
+    add_index :chunk_embeddings, :chunk_id
+    add_index :chunk_embeddings, :document_id
+    add_index :chunk_embeddings, [:embedding_provider, :embedding_model], name: 'idx_chunk_embeddings_provider_model'
+
+    add_index :search_queries, :created_at
+    add_index :query_results, :query_id
+    add_index :query_results, :similarity_score
+
+    # Create vector similarity indexes for fast search
+    # Using HNSW (Hierarchical Navigable Small World) for approximate nearest neighbor search
+
+    # Vector indexes for document embeddings
+    execute <<-SQL
+      CREATE INDEX idx_document_embeddings_cosine#{' '}
+      ON document_embeddings#{' '}
+      USING hnsw (embedding vector_cosine_ops)
+      WITH (m = 16, ef_construction = 64);
+    SQL
+
+    execute <<-SQL
+      CREATE INDEX idx_document_embeddings_l2#{' '}
+      ON document_embeddings#{' '}
+      USING hnsw (embedding vector_l2_ops)
+      WITH (m = 16, ef_construction = 64);
+    SQL
+
+    # Vector indexes for chunk embeddings
+    execute <<-SQL
+      CREATE INDEX idx_chunk_embeddings_cosine#{' '}
+      ON chunk_embeddings#{' '}
+      USING hnsw (embedding vector_cosine_ops)
+      WITH (m = 16, ef_construction = 64);
+    SQL
+
+    execute <<-SQL
+      CREATE INDEX idx_chunk_embeddings_l2#{' '}
+      ON chunk_embeddings#{' '}
+      USING hnsw (embedding vector_l2_ops)
+      WITH (m = 16, ef_construction = 64);
+    SQL
+
+    # Add helpful functions
+    execute <<-SQL
+      CREATE OR REPLACE FUNCTION cosine_similarity(a vector, b vector)
+      RETURNS float AS $$
+      BEGIN
+          RETURN 1 - (a <=> b);
+      END;
+      $$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
+    SQL
+
+    execute <<-SQL
+      CREATE OR REPLACE FUNCTION euclidean_distance(a vector, b vector)
+      RETURNS float AS $$
+      BEGIN
+          RETURN a <-> b;
+      END;
+      $$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
+    SQL
+  end
+
+  def down
+    drop_table :query_results
+    drop_table :search_queries
+    drop_table :chunk_embeddings
+    drop_table :document_chunks
+    drop_table :document_embeddings
+    drop_table :documents
+
+    execute 'DROP FUNCTION IF EXISTS cosine_similarity(vector, vector);'
+    execute 'DROP FUNCTION IF EXISTS euclidean_distance(vector, vector);'
+
+    disable_extension 'vector'
+  end
+end

data/docker-compose.yml

@@ -0,0 +1,153 @@
+# 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
+    container_name: prescient-ollama
+    ports:
+      - "11434:11434"
+    volumes:
+      # Persist models and data
+      - ollama_data:/root/.ollama
+      # Optional: Mount models from host for faster startup
+      # - ./models:/root/.ollama/models
+    environment:
+      # Optional: Set Ollama environment variables
+      - OLLAMA_HOST=0.0.0.0
+      - OLLAMA_ORIGINS=*
+    restart: unless-stopped
+    # Resource limits - adjust based on your hardware
+    deploy:
+      resources:
+        limits:
+          # Allocate most available memory for model loading
+          memory: 12G
+          cpus: '4.0'
+        reservations:
+          memory: 4G
+          cpus: '2.0'
+          # GPU support (uncomment if you have NVIDIA GPU)
+          # devices:
+          #   - driver: nvidia
+          #     count: 1
+          #     capabilities: [gpu]
+    # Optional: Shared memory for better performance
+    shm_size: 2g
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+  # Optional: Model initialization service
+  # This pulls required models on startup
+  ollama-init:
+    image: curlimages/curl:latest
+    container_name: prescient-ollama-init
+    depends_on:
+      ollama:
+        condition: service_healthy
+    volumes:
+      - ./scripts:/scripts:ro
+    command: |
+      sh -c '
+        echo "Pulling required models for Prescient..."
+        
+        # Pull embedding model
+        curl -X POST http://ollama:11434/api/pull \
+          -H "Content-Type: application/json" \
+          -d "{\"name\": \"nomic-embed-text\"}"
+        
+        # Pull chat model  
+        curl -X POST http://ollama:11434/api/pull \
+          -H "Content-Type: application/json" \
+          -d "{\"name\": \"llama3.1:8b\"}"
+        
+        echo "Models pulled successfully!"
+      '
+    restart: "no"
+
+  # PostgreSQL with pgvector extension for vector storage
+  postgres:
+    image: pgvector/pgvector:pg16
+    container_name: prescient-postgres
+    ports:
+      - "5432:5432"
+    environment:
+      - POSTGRES_DB=prescient_development
+      - POSTGRES_USER=prescient
+      - POSTGRES_PASSWORD=prescient_password
+      - POSTGRES_INITDB_ARGS=--auth-host=scram-sha-256
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./db/init:/docker-entrypoint-initdb.d:ro
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U prescient -d prescient_development"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+  # Optional: Redis for caching embeddings (useful for development)
+  redis:
+    image: redis:7-alpine
+    container_name: prescient-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+    command: redis-server --appendonly yes
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+
+  # Optional: Example Ruby application using Prescient
+  prescient-app:
+    build:
+      context: .
+      dockerfile: Dockerfile.example
+    container_name: prescient-example-app
+    depends_on:
+      ollama:
+        condition: service_healthy
+    environment:
+      # Ollama configuration
+      - OLLAMA_URL=http://ollama:11434
+      - OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+      - OLLAMA_CHAT_MODEL=llama3.1:8b
+      
+      # Optional: Other AI provider configurations
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      - HUGGINGFACE_API_KEY=${HUGGINGFACE_API_KEY:-}
+      
+      # Redis configuration (if using caching)
+      - REDIS_URL=redis://redis:6379/0
+    volumes:
+      # Mount your application code
+      - .:/app
+      - /app/vendor/bundle  # Bundle cache volume
+    working_dir: /app
+    # Keep container running for development
+    command: tail -f /dev/null
+    restart: unless-stopped
+
+volumes:
+  ollama_data:
+    driver: local
+  postgres_data:
+    driver: local
+  redis_data:
+    driver: local
+
+networks:
+  default:
+    name: prescient-network

data/examples/basic_usage.rb

@@ -0,0 +1,123 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Basic usage of the Prescient gem
+# This example shows how to use different providers for embeddings and text generation
+
+require_relative '../lib/prescient'
+
+# Example 1: Using default Ollama provider
+puts "=== Example 1: Default Ollama Provider ==="
+
+begin
+  # Create client using default provider (Ollama)
+  client = Prescient.client
+  
+  # Check if provider is available
+  if client.available?
+    puts "✅ Ollama is available"
+    
+    # Generate embedding
+    text = "Ruby is a dynamic programming language"
+    embedding = client.generate_embedding(text)
+    puts "📊 Generated embedding with #{embedding.length} dimensions"
+    
+    # Generate response
+    response = client.generate_response("What is Ruby programming language?")
+    puts "🤖 AI Response:"
+    puts response[:response]
+    puts "📈 Model: #{response[:model]}, Provider: #{response[:provider]}"
+  else
+    puts "❌ Ollama is not available"
+  end
+rescue Prescient::Error => e
+  puts "❌ Error with Ollama: #{e.message}"
+end
+
+# Example 2: Context-Aware Generation
+puts "\n=== Example 2: Context-Aware Generation ==="
+
+begin
+  client = Prescient.client
+  
+  # Simulate context items (would come from vector search in real applications)
+  context_items = [
+    {
+      'title' => 'Network Configuration Guide',
+      'content' => 'Network propagation typically takes 24-48 hours to complete globally. During this time, changes may not be visible from all locations.'
+    },
+    {
+      'title' => 'Technical FAQ',
+      'content' => 'DNS changes can take anywhere from a few minutes to 48 hours to propagate worldwide due to caching mechanisms.'
+    }
+  ]
+  
+  query = "How long does network propagation take?"
+  response = client.generate_response(query, context_items)
+  
+  puts "🔍 Query: #{query}"
+  puts "📋 Context: #{context_items.length} items"
+  puts "🤖 AI Response:"
+  puts response[:response]
+  
+rescue Prescient::Error => e
+  puts "❌ Error with context example: #{e.message}"
+end
+
+# Example 3: Provider comparison (if multiple providers configured)
+puts "\n=== Example 3: Provider Health Check ==="
+
+providers = [:ollama, :anthropic, :openai, :huggingface]
+
+providers.each do |provider_name|
+  begin
+    health = Prescient.health_check(provider: provider_name)
+    status_emoji = health[:status] == 'healthy' ? '✅' : '❌'
+    puts "#{status_emoji} #{provider_name.to_s.capitalize}: #{health[:status]}"
+    
+    if health[:ready]
+      puts "  Ready: #{health[:ready]}"
+    end
+    
+    if health[:models_available]
+      puts "  Models: #{health[:models_available].first(3).join(', ')}#{'...' if health[:models_available].length > 3}"
+    end
+    
+  rescue Prescient::Error => e
+    puts "❌ #{provider_name.to_s.capitalize}: #{e.message}"
+  end
+end
+
+# Example 4: Error handling
+puts "\n=== Example 4: Error Handling ==="
+
+begin
+  # Try to use a provider that might not be configured
+  client = Prescient.client(:nonexistent)
+rescue Prescient::Error => e
+  puts "❌ Expected error: #{e.message}"
+end
+
+# Example 5: Custom configuration
+puts "\n=== Example 5: Custom Configuration ==="
+
+Prescient.configure do |config|
+  config.timeout = 30
+  config.retry_attempts = 2
+  config.retry_delay = 0.5
+  
+  # Add custom Ollama configuration
+  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',
+    timeout: 60
+  )
+end
+
+puts "⚙️  Custom configuration applied"
+puts "   Timeout: #{Prescient.configuration.timeout}s"
+puts "   Retry attempts: #{Prescient.configuration.retry_attempts}"
+puts "   Providers: #{Prescient.configuration.providers.keys.join(', ')}"
+
+puts "\n🎉 Examples completed!"