prescient 0.4.0 → 0.6.0

data/examples/vector_search.rb

@@ -1,330 +1,94 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Example: Vector similarity search with Prescient gem and PostgreSQL pgvector
-# This example demonstrates how to store embeddings and perform similarity search
+# Example: Vector similarity search with Prescient and PostgreSQL pgvector.
+# The Store owns only its embedding table; applications own their documents.
 
 require_relative '../lib/prescient'
 require 'pg'
-require 'json'
 
-puts "=== Vector Similarity Search Example ==="
-puts "This example shows how to use Prescient with PostgreSQL pgvector for semantic search."
+puts '=== Vector Similarity Search Example ==='
 
-# Database connection configuration
 DB_CONFIG = {
-  host: ENV.fetch('DB_HOST', 'localhost'),
-  port: ENV.fetch('DB_PORT', '5432'),
-  dbname: ENV.fetch('DB_NAME', 'prescient_development'),
-  user: ENV.fetch('DB_USER', 'prescient'),
-  password: ENV.fetch('DB_PASSWORD', 'prescient_password')
+  host:     ENV.fetch('DB_HOST', 'localhost'),
+  port:     ENV.fetch('DB_PORT', '5432'),
+  dbname:   ENV.fetch('DB_NAME', 'prescient_development'),
+  user:     ENV.fetch('DB_USER', 'prescient'),
+  password: ENV.fetch('DB_PASSWORD', 'prescient_password'),
 }.freeze
 
 class VectorSearchExample
-  def initialize
-    @db = PG.connect(DB_CONFIG)
-    @client = Prescient.client(:ollama)
-  end
-
-  def run_example
-    puts "\n--- Setting up vector search example ---"
-    
-    # Check if services are available
-    unless check_services_available
-      puts "❌ Required services not available. Please start with: docker compose up -d"
-      return
-    end
-
-    # 1. Generate and store embeddings for existing documents
-    puts "\n📊 Generating embeddings for sample documents..."
-    generate_document_embeddings
-
-    # 2. Perform similarity search
-    puts "\n🔍 Performing similarity searches..."
-    search_examples
-
-    # 3. Advanced search with filtering
-    puts "\n🎯 Advanced search with metadata filtering..."
-    advanced_search_examples
-
-    # 4. Demonstrate different distance functions
-    puts "\n📏 Comparing different distance functions..."
-    compare_distance_functions
-
-    puts "\n🎉 Vector search example completed!"
-  end
-
-  private
+  EMBEDDING_DIMENSIONS = 768
+  EMBEDDING_MODEL = 'nomic-embed-text'
 
-  def check_services_available
-    # Check database connection
-    begin
-      result = @db.exec("SELECT 1")
-      puts "✅ PostgreSQL connected"
-    rescue PG::Error => e
-      puts "❌ PostgreSQL connection failed: #{e.message}"
-      return false
-    end
-
-    # Check pgvector extension
-    begin
-      result = @db.exec("SELECT * FROM pg_extension WHERE extname = 'vector'")
-      if result.ntuples > 0
-        puts "✅ pgvector extension available"
-      else
-        puts "❌ pgvector extension not found"
-        return false
-      end
-    rescue PG::Error => e
-      puts "❌ pgvector check failed: #{e.message}"
-      return false
-    end
-
-    # Check Ollama connection
-    if @client.available?
-      puts "✅ Ollama connected"
-    else
-      puts "❌ Ollama not available"
-      return false
-    end
-
-    true
+  def initialize
+    @connection = PG.connect(DB_CONFIG)
+    @client = Prescient.client(:ollama, enable_fallback: false)
+    @store = Prescient::Pgvector::Store.new(
+      connection: @connection,
+      dimensions: EMBEDDING_DIMENSIONS,
+    )
   end
 
-  def generate_document_embeddings
-    # Get documents that don't have embeddings yet
-    query = <<~SQL
-      SELECT d.id, d.title, d.content 
-      FROM documents d
-      LEFT JOIN document_embeddings de ON d.id = de.document_id 
-        AND de.embedding_provider = 'ollama' 
-        AND de.embedding_model = 'nomic-embed-text'
-      WHERE de.id IS NULL
-      LIMIT 10
-    SQL
-
-    result = @db.exec(query)
-    
-    if result.ntuples == 0
-      puts "   All documents already have embeddings"
-      return
+  def run
+    @store.install!
+    %i[cosine euclidean inner_product].each { |metric| @store.create_index!(metric:) }
+
+    documents.each do |document|
+      embedding = @client.generate_embedding(document[:content], model: EMBEDDING_MODEL)
+      @store.upsert(
+        id: document[:id],
+        embedding:,
+        provider: 'ollama',
+        model: EMBEDDING_MODEL,
+        content: document[:content],
+        metadata: { title: document[:title] },
+      )
     end
 
-    result.each do |row|
-      document_id = row['id']
-      title = row['title']
-      content = row['content']
-      
-      puts "   Generating embedding for: #{title}"
-      
-      begin
-        # Generate embedding using Prescient
-        embedding = @client.generate_embedding(content)
-        
-        # Store in database
-        insert_embedding(document_id, embedding, content, 'ollama', 'nomic-embed-text', 768)
-        
-        puts "   ✅ Stored embedding (#{embedding.length} dimensions)"
-        
-      rescue Prescient::Error => e
-        puts "   ❌ Failed to generate embedding: #{e.message}"
-      end
+    query = 'How do I improve database performance?'
+    embedding = @client.generate_embedding(query, model: EMBEDDING_MODEL)
+    results = @store.search(
+      embedding:,
+      limit: 3,
+      metric: :cosine,
+      provider: 'ollama',
+      model: EMBEDDING_MODEL,
+    )
+
+    puts "\nQuery: #{query}"
+    results.each_with_index do |result, index|
+      title = result[:metadata].fetch('title')
+      puts "#{index + 1}. #{title} (distance: #{result[:distance].round(4)})"
+      puts "   #{result[:content]}"
     end
+  rescue Prescient::Error, PG::Error => e
+    warn "Vector search failed: #{e.message}"
+  ensure
+    @connection&.close
   end
 
-  def insert_embedding(document_id, embedding, text, provider, model, dimensions)
-    # Convert Ruby array to PostgreSQL vector format
-    vector_str = "[#{embedding.join(',')}]"
-    
-    query = <<~SQL
-      INSERT INTO document_embeddings 
-      (document_id, embedding_provider, embedding_model, embedding_dimensions, embedding, embedding_text)
-      VALUES ($1, $2, $3, $4, $5, $6)
-    SQL
-    
-    @db.exec_params(query, [document_id, provider, model, dimensions, vector_str, text])
-  end
+  private
 
-  def search_examples
-    search_queries = [
-      "How to learn programming?",
-      "What is machine learning?",
-      "Database optimization techniques",
-      "API security best practices"
+  def documents
+    [
+      {
+        id:      'postgres-indexes',
+        title:   'PostgreSQL indexes',
+        content: 'Indexes can reduce query latency when their columns match common filters and ordering.',
+      },
+      {
+        id:      'ruby-performance',
+        title:   'Ruby performance',
+        content: 'Measure allocations and repeated work before optimizing a Ruby application.',
+      },
+      {
+        id:      'api-security',
+        title:   'API security',
+        content: 'Protect API credentials, validate inputs, and avoid exposing provider response bodies.',
+      },
     ]
-
-    search_queries.each do |query_text|
-      puts "\n🔍 Searching for: '#{query_text}'"
-      perform_similarity_search(query_text, limit: 3)
-    end
-  end
-
-  def perform_similarity_search(query_text, limit: 5, distance_function: 'cosine')
-    begin
-      # Generate embedding for query
-      query_embedding = @client.generate_embedding(query_text)
-      query_vector = "[#{query_embedding.join(',')}]"
-      
-      # Choose distance operator based on function
-      distance_op = case distance_function
-                   when 'cosine' then '<=>'
-                   when 'l2' then '<->'
-                   when 'inner_product' then '<#>'
-                   else '<=>'
-                   end
-
-      # Perform similarity search
-      search_query = <<~SQL
-        SELECT 
-          d.title,
-          d.content,
-          d.metadata,
-          de.embedding #{distance_op} $1::vector AS distance,
-          1 - (de.embedding <=> $1::vector) AS cosine_similarity
-        FROM documents d
-        JOIN document_embeddings de ON d.id = de.document_id
-        WHERE de.embedding_provider = 'ollama' 
-          AND de.embedding_model = 'nomic-embed-text'
-        ORDER BY de.embedding #{distance_op} $1::vector
-        LIMIT $2
-      SQL
-
-      result = @db.exec_params(search_query, [query_vector, limit])
-      
-      if result.ntuples == 0
-        puts "   No results found"
-        return
-      end
-
-      result.each_with_index do |row, index|
-        similarity = (row['cosine_similarity'].to_f * 100).round(1)
-        puts "   #{index + 1}. #{row['title']} (#{similarity}% similar)"
-        puts "      #{row['content'][0..100]}..."
-        
-        # Show metadata if available
-        if row['metadata'] && !row['metadata'].empty?
-          metadata = JSON.parse(row['metadata'])
-          tags = metadata['tags']&.join(', ')
-          puts "      Tags: #{tags}" if tags
-        end
-        puts
-      end
-      
-    rescue Prescient::Error => e
-      puts "   ❌ Search failed: #{e.message}"
-    rescue PG::Error => e
-      puts "   ❌ Database error: #{e.message}"
-    end
-  end
-
-  def advanced_search_examples
-    # Search with metadata filtering
-    puts "\n🎯 Search for programming content with beginner difficulty:"
-    advanced_search("programming basics", tags: ["programming"], difficulty: "beginner")
-    
-    puts "\n🎯 Search for AI/ML content:"
-    advanced_search("artificial intelligence", tags: ["ai", "machine-learning"])
   end
-
-  def advanced_search(query_text, filters = {})
-    begin
-      query_embedding = @client.generate_embedding(query_text)
-      query_vector = "[#{query_embedding.join(',')}]"
-      
-      # Build WHERE clause for metadata filtering
-      where_conditions = ["de.embedding_provider = 'ollama'", "de.embedding_model = 'nomic-embed-text'"]
-      params = [query_vector]
-      param_index = 2
-
-      filters.each do |key, value|
-        case key
-        when :tags
-          # Filter by tags array overlap
-          where_conditions << "d.metadata->'tags' ?| $#{param_index}::text[]"
-          params << value
-          param_index += 1
-        when :difficulty
-          # Filter by exact difficulty match
-          where_conditions << "d.metadata->>'difficulty' = $#{param_index}"
-          params << value
-          param_index += 1
-        when :source_type
-          # Filter by source type
-          where_conditions << "d.source_type = $#{param_index}"
-          params << value
-          param_index += 1
-        end
-      end
-
-      search_query = <<~SQL
-        SELECT 
-          d.title,
-          d.content,
-          d.metadata,
-          de.embedding <=> $1::vector AS cosine_distance,
-          1 - (de.embedding <=> $1::vector) AS cosine_similarity
-        FROM documents d
-        JOIN document_embeddings de ON d.id = de.document_id
-        WHERE #{where_conditions.join(' AND ')}
-        ORDER BY de.embedding <=> $1::vector
-        LIMIT 3
-      SQL
-
-      result = @db.exec_params(search_query, params)
-      
-      if result.ntuples == 0
-        puts "   No results found with the specified filters"
-        return
-      end
-
-      result.each_with_index do |row, index|
-        similarity = (row['cosine_similarity'].to_f * 100).round(1)
-        puts "   #{index + 1}. #{row['title']} (#{similarity}% similar)"
-        
-        metadata = JSON.parse(row['metadata'])
-        puts "      Difficulty: #{metadata['difficulty']}"
-        puts "      Tags: #{metadata['tags']&.join(', ')}"
-        puts "      #{row['content'][0..80]}..."
-        puts
-      end
-      
-    rescue Prescient::Error => e
-      puts "   ❌ Search failed: #{e.message}"
-    rescue PG::Error => e
-      puts "   ❌ Database error: #{e.message}"
-    end
-  end
-
-  def compare_distance_functions
-    query_text = "programming languages and development"
-    
-    puts "\n📏 Comparing distance functions for: '#{query_text}'"
-    
-    %w[cosine l2 inner_product].each do |distance_func|
-      puts "\n   #{distance_func.upcase} Distance:"
-      perform_similarity_search(query_text, limit: 2, distance_function: distance_func)
-    end
-  end
-
-  def cleanup
-    @db.close if @db
-  end
-end
-
-# Run the example
-begin
-  example = VectorSearchExample.new
-  example.run_example
-rescue StandardError => e
-  puts "❌ Example failed: #{e.message}"
-  puts e.backtrace.first(5).join("\n")
-ensure
-  example&.cleanup
 end
 
-puts "\n💡 Next steps:"
-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"
+VectorSearchExample.new.run

data/lib/prescient/api.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'stringio'
+require 'uri'
+require_relative '../prescient'
+
+# Dependency-free Rack-compatible HTTP application for Prescient operations.
+#
+# The application exposes only generic Prescient operations. It does not
+# expose provider-specific methods, credentials, or raw provider responses.
+class Prescient::API
+  # @return [Integer] Default maximum request body size in bytes
+  DEFAULT_MAX_BODY_BYTES = 1_048_576
+  # @return [Integer] Maximum number of inputs accepted by batch embeddings
+  MAX_BATCH_SIZE = 32
+  # @return [String] HTTP API version
+  API_VERSION = '1'
+  # @return [Hash<Array<String>, Symbol>] Generic HTTP route handlers
+  ROUTES = {
+    ['GET',  '/healthz']             => :healthz_response,
+    ['GET',  '/readyz']              => :readiness_response,
+    ['GET',  '/v1/version']          => :version_response,
+    ['GET',  '/v1/providers']        => :providers_response,
+    ['GET',  '/v1/models']           => :models_response,
+    ['GET',  '/v1/capabilities']     => :capabilities_response,
+    ['GET',  '/v1/health']           => :health_response,
+    ['POST', '/v1/generate']         => :generate_response,
+    ['POST', '/v1/embeddings']       => :embeddings_response,
+    ['POST', '/v1/embeddings/batch'] => :batch_embeddings_response,
+  }.freeze
+
+  # @param authentication [#call, nil] Optional authentication hook
+  # @param max_body_bytes [Integer] Maximum accepted request body size
+  # @return [void]
+  def initialize(authentication: nil, max_body_bytes: DEFAULT_MAX_BODY_BYTES)
+    @authentication = authentication
+    @max_body_bytes = validate_body_limit(max_body_bytes)
+  end
+
+  # Handle a Rack-style environment and return a Rack response tuple.
+  # @param env [Hash] Rack-compatible request environment
+  # @return [Array(Integer, Hash, Array<String>)] HTTP status, headers, body
+  def call(env)
+    request_id = request_id_for(env)
+    public_path = request_target(env).first
+    return dispatch(env, request_id) if ['/healthz', '/readyz'].include?(public_path)
+
+    unless authenticated?(env)
+      return response(401,
+                      error_payload('authentication_required', 'authentication required',
+                                    request_id))
+    end
+
+    dispatch(env, request_id)
+  rescue StandardError => e
+    handle_exception(e, request_id)
+  end
+
+  private
+
+  def dispatch(env, request_id)
+    method = env.fetch('REQUEST_METHOD', 'GET').upcase
+    path, query = request_target(env)
+    handler = ROUTES[[method, path]]
+    return response(404, error_payload('not_found', 'route not found', request_id)) unless handler
+
+    send(handler, env, query, request_id)
+  end
+
+  def healthz_response(_env, _query, request_id)
+    json_response(200, { status: 'ok' }, request_id)
+  end
+
+  def version_response(_env, _query, request_id)
+    json_response(200, { version: Prescient::VERSION, api_version: API_VERSION }, request_id)
+  end
+
+  def generate_response(env, _query, request_id)
+    payload = request_payload(env)
+    prompt = required_string(payload, 'prompt')
+    context = payload.fetch('context', [])
+    raise ArgumentError, 'context must be an array' unless context.is_a?(Array)
+
+    client = client_for(payload)
+    result = client.generate_response(prompt, context, **generation_options(payload))
+    json_response(200, result, request_id)
+  end
+
+  def embeddings_response(env, _query, request_id)
+    payload = request_payload(env)
+    input = required_string(payload, 'input')
+    client = client_for(payload)
+    result = client.generate_embedding(input, **model_options(payload))
+    json_response(200, embedding_payload(result, client), request_id)
+  end
+
+  def batch_embeddings_response(env, _query, request_id)
+    payload = request_payload(env)
+    inputs = payload['inputs']
+    raise ArgumentError, 'inputs must be a non-empty array' unless inputs.is_a?(Array) && inputs.any?
+    raise ArgumentError, "inputs cannot contain more than #{MAX_BATCH_SIZE} items" if inputs.length > MAX_BATCH_SIZE
+    raise ArgumentError, 'inputs must contain only strings' unless inputs.all?(String)
+
+    client = client_for(payload)
+    embeddings = inputs.map { |input| client.generate_embedding(input, **model_options(payload)) }
+    result = { embeddings: embeddings, dimensions: embeddings.first.length, provider: client.provider_name.to_s }
+    json_response(200,
+                  result, request_id)
+  end
+
+  def readiness_response(_env, _query, request_id)
+    providers = Prescient.configuration.providers.keys
+    ready = providers.any? { |name|
+      begin
+        Prescient.health_check(provider: name)[:ready] == true
+      rescue Prescient::Error
+        false
+      end
+    }
+    json_response(ready ? 200 : 503, { status: ready ? 'ready' : 'not_ready' }, request_id)
+  end
+
+  def providers_response(_env, _query, request_id)
+    providers = Prescient.configuration.providers.map { |name, registration|
+      { name: name.to_s, class: registration[:class].name }
+    }
+    json_response(200, { providers: providers }, request_id)
+  end
+
+  def models_response(_env, query, request_id)
+    names = query['provider'] ? [query['provider'].to_sym] : Prescient.configuration.providers.keys
+    models = names.flat_map { |name|
+      provider = Prescient.configuration.provider(name)
+      raise Prescient::Error, "Provider not configured: #{name}" unless provider
+
+      records = if provider.respond_to?(:list_models)
+                  provider.list_models
+                elsif provider.respond_to?(:available_models)
+                  provider.available_models
+                else
+                  []
+                end
+      records.map { |model| { provider: name.to_s, model: model } }
+    }
+    json_response(200, { models: models }, request_id)
+  end
+
+  def capabilities_response(_env, _query, request_id)
+    capabilities = Prescient.configuration.providers.map { |name, registration|
+      provider = registration[:class]
+      {
+        provider:      name.to_s,
+        generation:    provider.method_defined?(:generate_response),
+        embeddings:    provider.method_defined?(:generate_embedding),
+        health:        provider.method_defined?(:health_check),
+        model_listing: provider.method_defined?(:list_models) || provider.method_defined?(:available_models),
+      }
+    }
+    json_response(200, { capabilities: capabilities }, request_id)
+  end
+
+  def health_response(_env, query, request_id)
+    if query['provider']
+      json_response(200, Prescient.health_check(provider: query['provider'].to_sym), request_id)
+    else
+      results = Prescient.configuration.providers.keys.to_h { |name|
+        [name.to_s, Prescient.health_check(provider: name)]
+      }
+      json_response(200, results, request_id)
+    end
+  end
+
+  def client_for(payload)
+    provider = payload['provider']&.to_sym
+    fallback = payload.key?('fallback') ? payload['fallback'] : true
+    raise ArgumentError, 'fallback must be boolean' unless [true, false].include?(fallback)
+
+    Prescient.client(provider, enable_fallback: fallback)
+  end
+
+  def generation_options(payload)
+    options = model_options(payload)
+    ['temperature', 'max_tokens', 'top_p'].each do |key|
+      options[key.to_sym] = payload[key] if payload.key?(key)
+    end
+    options
+  end
+
+  def model_options(payload)
+    payload['model'] ? { model: payload['model'] } : {}
+  end
+
+  def embedding_payload(embedding, client)
+    { embedding: embedding, dimensions: embedding.length, provider: client.provider_name.to_s }
+  end
+
+  def request_payload(env)
+    content_length = env['CONTENT_LENGTH'].to_i
+    raise ArgumentError, 'request body exceeds configured limit' if content_length > @max_body_bytes
+
+    body = env.fetch('rack.input', StringIO.new).read(@max_body_bytes + 1)
+    raise ArgumentError, 'request body exceeds configured limit' if body.bytesize > @max_body_bytes
+
+    parsed = JSON.parse(body)
+    raise ArgumentError, 'request body must contain a JSON object' unless parsed.is_a?(Hash)
+
+    parsed
+  end
+
+  def required_string(payload, key)
+    value = payload[key]
+    raise ArgumentError, "#{key} must be a non-empty string" unless value.is_a?(String) && !value.empty?
+
+    value
+  end
+
+  def request_target(env)
+    target = env['REQUEST_URI'] || env['PATH_INFO'] || '/'
+    path, query = target.split('?', 2)
+    [path, URI.decode_www_form(query.to_s).to_h]
+  end
+
+  def authenticated?(env)
+    return true unless @authentication
+
+    @authentication.call(env) == true
+  end
+
+  def request_id_for(env)
+    supplied = env['HTTP_X_REQUEST_ID'].to_s
+    supplied.match?(/\A[a-zA-Z0-9._:-]{1,128}\z/) ? supplied : SecureRandom.uuid
+  end
+
+  def json_response(status, payload, request_id)
+    response(status, payload.merge(request_id: request_id))
+  end
+
+  def response(status, payload)
+    body = JSON.generate(payload)
+    headers = {
+      'content-type'   => 'application/json',
+      'content-length' => body.bytesize.to_s,
+    }
+    headers['x-request-id'] = payload[:request_id] if payload[:request_id]
+    [status, headers, [body]]
+  end
+
+  def error_payload(type, message, request_id)
+    { error: { type: type, message: message }, request_id: request_id }
+  end
+
+  def error_type(error)
+    error.class.name.split('::').last.delete_suffix('Error').downcase
+  end
+
+  def error_status(error)
+    return 401 if error.is_a?(Prescient::AuthenticationError)
+    return 429 if error.is_a?(Prescient::RateLimitError)
+    return 503 if error.is_a?(Prescient::ConnectionError) || error.is_a?(Prescient::ProviderError)
+    return 422 if error.is_a?(Prescient::ModelNotAvailableError)
+
+    500
+  end
+
+  def handle_exception(error, request_id)
+    case error
+    when JSON::ParserError
+      response(400, error_payload('invalid_json', 'request body must contain valid JSON', request_id))
+    when ArgumentError
+      response(400, error_payload('invalid_request', error.message, request_id))
+    when Prescient::Error
+      response(error_status(error), error_payload(error_type(error), error.message, request_id))
+    else
+      response(500, error_payload('internal_error', 'internal server error', request_id))
+    end
+  end
+
+  def validate_body_limit(value)
+    return value if value.is_a?(Integer) && value.positive?
+
+    raise ArgumentError, 'max_body_bytes must be a positive integer'
+  end
+end