prescient 0.0.0 → 0.2.0

data/lib/prescient/provider/ollama.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'httparty'
+
+class Prescient::Provider::Ollama < Prescient::Base
+  include HTTParty
+
+  EMBEDDING_DIMENSIONS = 768 # nomic-embed-text dimensions
+
+  def initialize(**options)
+    super
+    self.class.base_uri(@options[:url])
+    self.class.default_timeout(@options[:timeout] || 60)
+  end
+
+  def generate_embedding(text, **_options)
+    handle_errors do
+      embedding = fetch_and_parse('post', '/api/embeddings',
+                                  root_key: 'embedding',
+                                  headers:  { 'Content-Type' => 'application/json' },
+                                  body:     {
+                                    model:  @options[:embedding_model],
+                                    prompt: clean_text(text),
+                                  }.to_json)
+
+      raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding
+
+      normalize_embedding(embedding, EMBEDDING_DIMENSIONS)
+    end
+  end
+
+  def generate_response(prompt, context_items = [], **options)
+    handle_errors do
+      request_options = prepare_generate_response(prompt, context_items, **options)
+
+      # Make the request and store both text and full response
+      response = self.class.post('/api/generate', **request_options)
+      validate_response!(response, 'POST /api/generate')
+
+      generated_text = response.parsed_response['response']
+      raise Prescient::InvalidResponseError, 'No response generated' unless generated_text
+
+      {
+        response:        generated_text.strip,
+        model:           @options[:chat_model],
+        provider:        'ollama',
+        processing_time: response.parsed_response['total_duration']&./(1_000_000_000.0),
+        metadata:        {
+          eval_count:        response.parsed_response['eval_count'],
+          eval_duration:     response.parsed_response['eval_duration'],
+          prompt_eval_count: response.parsed_response['prompt_eval_count'],
+        },
+      }
+    end
+  end
+
+  def health_check
+    handle_errors do
+      models = available_models
+      embedding_available = models.any? { |m| m[:embedding] }
+      chat_available = models.any? { |m| m[:chat] }
+
+      {
+        status:           'healthy',
+        provider:         'ollama',
+        url:              @options[:url],
+        models_available: models.map { |m| m[:name] },
+        embedding_model:  {
+          name:      @options[:embedding_model],
+          available: embedding_available,
+        },
+        chat_model:       {
+          name:      @options[:chat_model],
+          available: chat_available,
+        },
+        ready:            embedding_available && chat_available,
+      }
+    end
+  rescue Prescient::Error => e
+    {
+      status:   'unavailable',
+      provider: 'ollama',
+      error:    e.class.name,
+      message:  e.message,
+      url:      @options[:url],
+    }
+  end
+
+  def available_models
+    return @_available_models if defined?(@_available_models)
+
+    handle_errors do
+      @_available_models = (fetch_and_parse('get', '/api/tags', root_key: 'models') || []).map { |model|
+        { embedding:  model['name'] == @options[:embedding_model],
+          chat:       model['name'] == @options[:chat_model],
+          name: model['name'], size: model['size'], modified_at: model['modified_at'], digest: model['digest'] }
+      }
+    end
+  end
+
+  def pull_model(model_name)
+    handle_errors do
+      fetch_and_parse('post', '/api/pull',
+                      headers: { 'Content-Type' => 'application/json' },
+                      body:    { name: model_name }.to_json,
+                      timeout: 300) # 5 minutes for model download
+      {
+        success: true,
+        model:   model_name,
+        message: "Model #{model_name} pulled successfully",
+      }
+    end
+  end
+
+  protected
+
+  def validate_configuration!
+    required_options = [:url, :embedding_model, :chat_model]
+    missing_options = required_options.select { |opt| @options[opt].nil? }
+
+    return unless missing_options.any?
+
+    raise Prescient::Error, "Missing required options: #{missing_options.join(', ')}"
+  end
+
+  private
+
+  def prepare_generate_response(prompt, context_items = [], **options)
+    formatted_prompt = build_prompt(prompt, context_items)
+    { root_key: 'response',
+      headers:  { 'Content-Type' => 'application/json' },
+      body:     {
+        model:   @options[:chat_model],
+        prompt:  formatted_prompt,
+        stream:  false,
+        options: {
+          num_predict: options[:max_tokens] || 2000,
+          temperature: options[:temperature] || 0.7,
+          top_p:       options[:top_p] || 0.9,
+        },
+      }.to_json }
+  end
+
+  def fetch_and_parse(htt_verb, endpoint, **options)
+    options = options.dup
+    root_key = options.delete(:root_key)
+
+    response = self.class.send(htt_verb, endpoint, **options)
+    validate_response!(response, "#{htt_verb.upcase} #{endpoint}")
+    return unless root_key
+
+    response.parsed_response[root_key]
+  end
+
+  def validate_response!(response, operation)
+    return if response.success?
+
+    case response.code
+    when 404
+      raise Prescient::ModelNotAvailableError, "Model not available for #{operation}"
+    when 429
+      raise Prescient::RateLimitError, "Rate limit exceeded for #{operation}"
+    when 401, 403
+      raise Prescient::AuthenticationError, "Authentication failed for #{operation}"
+    when 500..599
+      raise Prescient::Error, "Ollama server error during #{operation}: #{response.body}"
+    else
+      raise Prescient::Error,
+            "Ollama request failed for #{operation}: HTTP #{response.code} - #{response.message}"
+    end
+  end
+end

data/lib/prescient/provider/openai.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'httparty'
+
+class Prescient::Provider::OpenAI < Prescient::Base
+  include HTTParty
+
+  base_uri 'https://api.openai.com'
+
+  EMBEDDING_DIMENSIONS = {
+    'text-embedding-3-small' => 1536,
+    'text-embedding-3-large' => 3072,
+    'text-embedding-ada-002' => 1536,
+  }.freeze
+
+  def initialize(**options)
+    super
+    self.class.default_timeout(@options[:timeout] || 60)
+  end
+
+  def generate_embedding(text, **_options)
+    handle_errors do
+      clean_text_input = clean_text(text)
+
+      response = self.class.post('/v1/embeddings',
+                                 headers: {
+                                   'Content-Type'  => 'application/json',
+                                   'Authorization' => "Bearer #{@options[:api_key]}",
+                                 },
+                                 body:    {
+                                   model:           @options[:embedding_model],
+                                   input:           clean_text_input,
+                                   encoding_format: 'float',
+                                 }.to_json)
+
+      validate_response!(response, 'embedding generation')
+
+      embedding_data = response.parsed_response.dig('data', 0, 'embedding')
+      raise Prescient::InvalidResponseError, 'No embedding returned' unless embedding_data
+
+      expected_dimensions = EMBEDDING_DIMENSIONS[@options[:embedding_model]] || 1536
+      normalize_embedding(embedding_data, expected_dimensions)
+    end
+  end
+
+  def generate_response(prompt, context_items = [], **options)
+    handle_errors do
+      formatted_prompt = build_prompt(prompt, context_items)
+
+      response = self.class.post('/v1/chat/completions',
+                                 headers: {
+                                   'Content-Type'  => 'application/json',
+                                   'Authorization' => "Bearer #{@options[:api_key]}",
+                                 },
+                                 body:    {
+                                   model:       @options[:chat_model],
+                                   messages:    [
+                                     {
+                                       role:    'user',
+                                       content: formatted_prompt,
+                                     },
+                                   ],
+                                   max_tokens:  options[:max_tokens] || 2000,
+                                   temperature: options[:temperature] || 0.7,
+                                   top_p:       options[:top_p] || 0.9,
+                                 }.to_json)
+
+      validate_response!(response, 'text generation')
+
+      content = response.parsed_response.dig('choices', 0, 'message', 'content')
+      raise Prescient::InvalidResponseError, 'No response generated' unless content
+
+      {
+        response:        content.strip,
+        model:           @options[:chat_model],
+        provider:        'openai',
+        processing_time: nil,
+        metadata:        {
+          usage:         response.parsed_response['usage'],
+          finish_reason: response.parsed_response.dig('choices', 0, 'finish_reason'),
+        },
+      }
+    end
+  end
+
+  def health_check
+    handle_errors do
+      response = self.class.get('/v1/models',
+                                headers: {
+                                  'Authorization' => "Bearer #{@options[:api_key]}",
+                                })
+
+      if response.success?
+        models = response.parsed_response['data'] || []
+        embedding_available = models.any? { |m| m['id'] == @options[:embedding_model] }
+        chat_available = models.any? { |m| m['id'] == @options[:chat_model] }
+
+        {
+          status:           'healthy',
+          provider:         'openai',
+          models_available: models.map { |m| m['id'] },
+          embedding_model:  {
+            name:      @options[:embedding_model],
+            available: embedding_available,
+          },
+          chat_model:       {
+            name:      @options[:chat_model],
+            available: chat_available,
+          },
+          ready:            embedding_available && chat_available,
+        }
+      else
+        {
+          status:   'unhealthy',
+          provider: 'openai',
+          error:    "HTTP #{response.code}",
+          message:  response.message,
+        }
+      end
+    end
+  rescue Prescient::Error => e
+    {
+      status:   'unavailable',
+      provider: 'openai',
+      error:    e.class.name,
+      message:  e.message,
+    }
+  end
+
+  def list_models
+    handle_errors do
+      response = self.class.get('/v1/models',
+                                headers: {
+                                  'Authorization' => "Bearer #{@options[:api_key]}",
+                                })
+      validate_response!(response, 'model listing')
+
+      models = response.parsed_response['data'] || []
+      models.map do |model|
+        {
+          name:     model['id'],
+          created:  model['created'],
+          owned_by: model['owned_by'],
+        }
+      end
+    end
+  end
+
+  protected
+
+  def validate_configuration!
+    required_options = [:api_key, :embedding_model, :chat_model]
+    missing_options = required_options.select { |opt| @options[opt].nil? }
+
+    return unless missing_options.any?
+
+    raise Prescient::Error, "Missing required options: #{missing_options.join(', ')}"
+  end
+
+  private
+
+  def validate_response!(response, operation)
+    return if response.success?
+
+    case response.code
+    when 400
+      raise Prescient::Error, "Bad request for #{operation}: #{response.body}"
+    when 401
+      raise Prescient::AuthenticationError, "Authentication failed for #{operation}"
+    when 403
+      raise Prescient::AuthenticationError, "Forbidden access for #{operation}"
+    when 429
+      raise Prescient::RateLimitError, "Rate limit exceeded for #{operation}"
+    when 500..599
+      raise Prescient::Error, "OpenAI server error during #{operation}: #{response.body}"
+    else
+      raise Prescient::Error,
+            "OpenAI request failed for #{operation}: HTTP #{response.code} - #{response.message}"
+    end
+  end
+end

data/lib/prescient/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Prescient
-  VERSION = "0.0.0"
+  VERSION = '0.2.0'
 end

data/lib/prescient.rb

@@ -1,8 +1,192 @@
 # frozen_string_literal: true
 
-require_relative "prescient/version"
+require_relative 'prescient/version'
 
+# Main Prescient module for AI provider abstraction
+#
+# Prescient provides a unified interface for working with multiple AI providers
+# including Ollama, OpenAI, Anthropic, and HuggingFace. It supports both
+# embedding generation and text completion with configurable context handling.
+#
+# @example Basic usage
+#   Prescient.configure do |config|
+#     config.add_provider(:openai, Prescient::Provider::OpenAI,
+#                         api_key: 'your-api-key')
+#   end
+#
+#   client = Prescient.client(:openai)
+#   response = client.generate_response("Hello, world!")
+#
+# @example Embedding generation
+#   embedding = client.generate_embedding("Some text to embed")
+#   puts embedding.length # => 1536 (for OpenAI text-embedding-3-small)
+#
+# @author Claude Code
+# @since 1.0.0
 module Prescient
+  # Base error class for all Prescient-specific errors
   class Error < StandardError; end
-  # Your code goes here...
+
+  # 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
+
+  # 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
+end
+
+require_relative 'prescient/base'
+require_relative 'prescient/provider/ollama'
+require_relative 'prescient/provider/anthropic'
+require_relative 'prescient/provider/openai'
+require_relative 'prescient/provider/huggingface'
+require_relative 'prescient/client'
+
+module Prescient
+  # Configure Prescient with custom settings and providers
+  #
+  # @example Configure with custom provider
+  #   Prescient.configure do |config|
+  #     config.default_provider = :openai
+  #     config.timeout = 60
+  #     config.add_provider(:openai, Prescient::Provider::OpenAI,
+  #                         api_key: 'your-key')
+  #   end
+  #
+  # @yield [config] Configuration block
+  # @yieldparam config [Configuration] The configuration object
+  # @return [void]
+  def self.configure
+    yield(configuration)
+  end
+
+  # Get the current configuration instance
+  #
+  # @return [Configuration] The current configuration
+  def self.configuration
+    @_configuration ||= Configuration.new
+  end
+
+  # Reset configuration to defaults
+  #
+  # @return [Configuration] New configuration instance
+  def self.reset_configuration!
+    @_configuration = Configuration.new
+  end
+
+  # Configuration class for managing Prescient settings and providers
+  #
+  # Handles global settings like timeouts and retry behavior, as well as
+  # provider registration and instantiation.
+  class Configuration
+    # @return [Symbol] The default provider to use when none specified
+    attr_accessor :default_provider
+
+    # @return [Integer] Default timeout in seconds for API requests
+    attr_accessor :timeout
+
+    # @return [Integer] Number of retry attempts for failed requests
+    attr_accessor :retry_attempts
+
+    # @return [Float] Delay between retry attempts in seconds
+    attr_accessor :retry_delay
+
+    # @return [Array<Symbol>] List of fallback providers to try when primary fails
+    attr_accessor :fallback_providers
+
+    # @return [Hash] Registered providers configuration
+    attr_reader :providers
+
+    # Initialize configuration with default values
+    def initialize
+      @default_provider = :ollama
+      @timeout = 30
+      @retry_attempts = 3
+      @retry_delay = 1.0
+      @fallback_providers = []
+      @providers = {}
+    end
+
+    # Register a new AI provider
+    #
+    # @param name [Symbol] Unique identifier for the provider
+    # @param provider_class [Class] Provider class that inherits from Base
+    # @param options [Hash] Configuration options for the provider
+    # @option options [String] :api_key API key for authenticated providers
+    # @option options [String] :url Base URL for self-hosted providers
+    # @option options [String] :model, :chat_model Model name for text generation
+    # @option options [String] :embedding_model Model name for embeddings
+    # @return [void]
+    #
+    # @example Add OpenAI provider
+    #   config.add_provider(:openai, Prescient::Provider::OpenAI,
+    #                       api_key: 'sk-...',
+    #                       chat_model: 'gpt-4')
+    def add_provider(name, provider_class, **options)
+      @providers[name.to_sym] = {
+        class:   provider_class,
+        options: options,
+      }
+    end
+
+    # Instantiate a provider by name
+    #
+    # @param name [Symbol] The provider name
+    # @return [Base, nil] Provider instance or nil if not found
+    def provider(name)
+      provider_config = @providers[name.to_sym]
+      return nil unless provider_config
+
+      provider_config[:class].new(**provider_config[:options])
+    end
+
+    # Get list of available providers (those that are configured and healthy)
+    #
+    # @return [Array<Symbol>] List of available provider names
+    def available_providers
+      @providers.keys.select do |name|
+        provider(name)&.available?
+      rescue StandardError
+        false
+      end
+    end
+  end
+
+  # Default configuration
+  configure do |config|
+    config.add_provider(:ollama, Prescient::Provider::Ollama,
+                        url:             ENV.fetch('OLLAMA_URL', 'http://localhost:11434'),
+                        embedding_model: ENV.fetch('OLLAMA_EMBEDDING_MODEL', 'nomic-embed-text'),
+                        chat_model:      ENV.fetch('OLLAMA_CHAT_MODEL', 'llama3.1:8b'))
+
+    config.add_provider(:anthropic, Prescient::Provider::Anthropic,
+                        api_key: ENV.fetch('ANTHROPIC_API_KEY', nil),
+                        model:   ENV.fetch('ANTHROPIC_MODEL', 'claude-3-haiku-20240307'))
+
+    config.add_provider(:openai, Prescient::Provider::OpenAI,
+                        api_key:         ENV.fetch('OPENAI_API_KEY', nil),
+                        embedding_model: ENV.fetch('OPENAI_EMBEDDING_MODEL', 'text-embedding-3-small'),
+                        chat_model:      ENV.fetch('OPENAI_CHAT_MODEL', 'gpt-3.5-turbo'))
+
+    config.add_provider(:huggingface, Prescient::Provider::HuggingFace,
+                        api_key:         ENV.fetch('HUGGINGFACE_API_KEY', nil),
+                        embedding_model: ENV.fetch('HUGGINGFACE_EMBEDDING_MODEL', 'sentence-transformers/all-MiniLM-L6-v2'),
+                        chat_model:      ENV.fetch('HUGGINGFACE_CHAT_MODEL', 'microsoft/DialoGPT-medium'))
+  end
 end

data/prescient.gemspec

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "lib/prescient/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "prescient"
+  spec.version = Prescient::VERSION
+  spec.authors = ["Ken C. Demanawa"]
+  spec.email = ["kenneth.c.demanawa@gmail.com"]
+
+  spec.summary = "Prescient AI provider abstraction for Ruby applications"
+  spec.description = "Prescient provides a unified interface for AI providers including local Ollama, Anthropic Claude, OpenAI GPT, and HuggingFace models. Built for AI applications with error handling, health monitoring, and provider switching."
+  spec.homepage = "https://github.com/yourcompany/prescient"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/yourcompany/prescient"
+  spec.metadata["changelog_uri"] = "https://github.com/yourcompany/prescient/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "httparty", "~> 0.23.1"
+
+  # Optional dependencies for vector database integration
+  spec.add_development_dependency "pg", "~> 1.6" # PostgreSQL adapter for pgvector integration
+
+  # Development dependencies
+  spec.add_development_dependency "minitest", "~> 5.25"
+  spec.add_development_dependency "mocha", "~> 2.7"
+  spec.add_development_dependency "webmock", "~> 3.25"
+  spec.add_development_dependency "vcr", "~> 6.3"
+  spec.add_development_dependency "rubocop", "~> 1.79"
+  spec.add_development_dependency "rubocop-minitest", "~> 0.38.1"
+  spec.add_development_dependency "rubocop-performance", "~> 1.25"
+  spec.add_development_dependency "rubocop-rake", "~> 0.7.1"
+  spec.add_development_dependency "simplecov", "~> 0.22.0"
+  spec.add_development_dependency "rake", "~> 13.3"
+  spec.add_development_dependency "irb", "~> 1.15"
+  spec.add_development_dependency "yard", "~> 0.9.37"
+  spec.add_development_dependency "kramdown", "~> 2.5"
+end

data/scripts/setup-ollama-models.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Setup script for pulling required Ollama models for Prescient gem
+
+set -e
+
+OLLAMA_URL=${OLLAMA_URL:-"http://localhost:11434"}
+EMBEDDING_MODEL=${OLLAMA_EMBEDDING_MODEL:-"nomic-embed-text"}
+CHAT_MODEL=${OLLAMA_CHAT_MODEL:-"llama3.1:8b"}
+
+echo "🚀 Setting up Ollama models for Prescient gem..."
+echo "Ollama URL: $OLLAMA_URL"
+
+# Function to check if Ollama is ready
+wait_for_ollama() {
+    echo "⏳ Waiting for Ollama to be ready..."
+    local max_attempts=30
+    local attempt=1
+    
+    while [ $attempt -le $max_attempts ]; do
+        if curl -s "$OLLAMA_URL/api/tags" > /dev/null 2>&1; then
+            echo "✅ Ollama is ready!"
+            return 0
+        fi
+        
+        echo "Attempt $attempt/$max_attempts - Ollama not ready yet..."
+        sleep 2
+        ((attempt++))
+    done
+    
+    echo "❌ Ollama failed to start within expected time"
+    exit 1
+}
+
+# Function to pull a model
+pull_model() {
+    local model_name=$1
+    echo "📦 Pulling model: $model_name"
+    
+    if curl -s -X POST "$OLLAMA_URL/api/pull" \
+        -H "Content-Type: application/json" \
+        -d "{\"name\": \"$model_name\"}" | grep -q "success"; then
+        echo "✅ Successfully pulled $model_name"
+    else
+        echo "⚠️  Model pull initiated for $model_name (this may take a while)"
+        # Wait a bit and check if model appears in list
+        sleep 5
+    fi
+}
+
+# Function to list available models
+list_models() {
+    echo "📋 Available models:"
+    curl -s "$OLLAMA_URL/api/tags" | jq -r '.models[]?.name // empty' 2>/dev/null || echo "Unable to list models"
+}
+
+# Main execution
+main() {
+    wait_for_ollama
+    
+    echo "🔧 Current models:"
+    list_models
+    
+    echo "📥 Pulling required models..."
+    pull_model "$EMBEDDING_MODEL"
+    pull_model "$CHAT_MODEL"
+    
+    echo "✨ Model setup complete!"
+    echo "📋 Final model list:"
+    list_models
+    
+    echo ""
+    echo "🎉 Ollama is ready for use with Prescient gem!"
+    echo "💡 You can now run the examples with:"
+    echo "   OLLAMA_URL=$OLLAMA_URL ruby examples/custom_contexts.rb"
+}
+
+main "$@"