prescient 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62c70c521da514a785f44beb284287d56a3affd451160bcc8bcad26fff713303
-  data.tar.gz: 4b7a41690ae8395cb57ccefee607764d850256d6fe9c4341db038e28ee67c7ce
+  metadata.gz: a54256e23ba55fc2492fae38d687b275dcb2362df73449d3212bd03659150717
+  data.tar.gz: 73ab805b7a5781a1d03488605ae8d7890feda7344b41b1ac550343484b3b597a
 SHA512:
-  metadata.gz: 5cff60610144acef5b2be9693dbe87f1bb7b231dae219ac5cc826c2720fb383ed7c6df580cfe9a9ac26eb56812bc841178d605272adde63054506006cfdd9575
-  data.tar.gz: c6f3eef2edcd1f53eb0c41a779db4b4aae36990e40b91ff406077353fd8c9d3b10332c2c5701a17ba88c3fb2debec6eb4e8560eb14a9c483e387dc146d5f6b18
+  metadata.gz: e918a87b3e09affe9d5a002a3955051e7729ee565f84c42c534c99dc3fc70371fda930e63cc90801da07b4c4f5e48031c41e952088dfc3de24f0f38b579e9567
+  data.tar.gz: feb707947b7cc0b67d8bff933b4c584a69595b9b5e1dd3f214b4c4aa2d48c0577c996b542c238fbcef337f0f276a1bb995acc9653e8fad32262a6f6fa17caaf4

data/.rubocop.yml

@@ -9,12 +9,10 @@ plugins:
   - rubocop-rake
 
 AllCops:
-  # Target Ruby 3.0+ (matches gemspec requirement)
-  TargetRubyVersion: 3.0
-
+  # Target Ruby 3.1+ (matches gemspec requirement)
+  TargetRubyVersion: 3.1
   # Use new cops by default
   NewCops: enable
-
   # Exclude common directories
   Exclude:
     - 'vendor/**/*'
@@ -169,11 +167,13 @@ Metrics/ModuleLength:
   Max: 150
 
 Metrics/ClassLength:
+  Enabled: false
   Max: 150
   Exclude:
     - 'test/**/*'
 
 Metrics/MethodLength:
+  Enabled: false
   Max: 25
   Exclude:
     - 'test/**/*'
@@ -181,6 +181,7 @@ Metrics/MethodLength:
     - 'lib/prescient/provider/*.rb'
 
 Metrics/BlockLength:
+  Enabled: false
   Max: 25
   Exclude:
     - 'test/**/*'
@@ -199,6 +200,7 @@ Metrics/CyclomaticComplexity:
     - 'lib/prescient/provider/*.rb'
 
 Metrics/PerceivedComplexity:
+  Enabled: false
   Max: 8
   Exclude:
     - 'lib/prescient/provider/*.rb'

data/.yardopts

@@ -0,0 +1,11 @@
+--title "Prescient API Documentation"
+--protected
+--markup markdown
+
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE.txt
+INTEGRATION_GUIDE.md
+VECTOR_SEARCH_GUIDE.md

data/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+## Unreleased
+
+## [0.3.0] - 2025-08-14
+
+### Added
+
+- Added a development quality harness covering tests, RuboCop, YARD, and RBS tasks.
+- Added 99% minimum line and branch coverage requirements with expanded provider and context coverage tests.
+- Added an actionlint Rake task for GitHub Actions validation.
+- Added Dependabot configuration for Bundler, Docker, and GitHub Actions updates.
+- Added an opt-in `Prescient::Pgvector::Store` boundary for validated embedding storage and similarity search.
+- Added configurable Ollama embedding dimensions while preserving strict validation when configured.
+- Added a default example-syntax quality gate that validates Ruby examples without contacting providers.
+
+### Changed
+
+- Updated Ollama embeddings to use `/api/embed` with strict vector-dimension validation.
+- Restricted fallback to transient/provider-service failures and added the public `ProviderError` exception for provider-side service errors.
+- Reused registered provider instances and removed redundant health checks during fallback discovery.
+- Updated default chat model names and README examples for current Ollama, Anthropic, OpenAI, and Hugging Face model selections.
+- Updated Hugging Face inference to use the current router feature-extraction and OpenAI-compatible chat-completion APIs.
+- Standardized provider reachability in health results and removed embedding padding/truncation across OpenAI and Hugging Face.
+- Updated Anthropic model listing and health checks to use its `/v1/models` catalog endpoint.
+- Retained OpenAI Chat Completions for the current normalized public response contract; Responses API migration remains a separately scoped compatibility change.
+- Raised YARD API documentation coverage enforcement to 99% or higher and modernized gem development metadata.
+- Compacted GitHub Actions into focused CI, Pages, release, and security workflows.
+- Added credentialed, provider-selected live smoke tests that remain skipped by default.
+- Restored the RBS/Steep development tasks with a committed Steepfile and curated core API signatures.
+- Expanded Steep coverage to the base abstraction and all provider adapters, including their public operations and HTTP boundaries.
+- Added configurable provider-info sensitive-key sanitization and configurable generic context-field exclusions.
+- Audited README and documentation examples against the current codebase.
+- Removed client `method_missing` delegation so provider-specific behavior is not exposed through the public client.
+- Prevented default provider registration when required credentials are absent from the environment.
+- Sanitized provider HTTP errors so raw response bodies are not exposed in exception messages.
+- Removed fallback health probes before provider operations to avoid duplicate network requests and race conditions.
+- Clarified health semantics: `reachable` reports transport availability and `ready` reports configured-model readiness.
+- Added shared provider health-contract coverage for status, reachability, readiness, and provider identity.
+
+### Removed
+
+- Removed the obsolete PDF changelog and superseded workflow definitions.
+
+## [0.2.0] - 2025-08-05
+
+### Added
+
+- Added new featire: Providers fallbacks mechanism
+
+## [0.1.0] - 2025-08-05
+
+### Added
+
+- Initial release of Prescient gem
+- Support for four AI providers:
+  - **Ollama**: Local AI provider with embedding and text generation
+  - **Anthropic**: Claude models for text generation
+  - **OpenAI**: GPT models and embeddings
+  - **HuggingFace**: Open-source models and embeddings
+- Unified client interface for all providers
+- Comprehensive error handling with provider-specific exceptions:
+  - `ConnectionError` for network issues
+  - `AuthenticationError` for API key problems
+  - `RateLimitError` for rate limiting
+  - `ModelNotAvailableError` for missing models
+  - `InvalidResponseError` for malformed responses
+- Automatic retry logic with configurable attempts and delays
+- Health monitoring capabilities for all providers
+- Environment variable configuration support
+- Programmatic configuration system
+- Context-aware generation support with context items
+- Text preprocessing and embedding normalization
+- Provider availability checking
+- Model listing capabilities (where supported)
+- Comprehensive test suite with RSpec
+- Documentation and usage examples
+
+### Provider-Specific Features
+
+- **Ollama**: Model management (pull, list), local deployment
+- **Anthropic**: Latest Claude 3 models (Haiku, Sonnet, Opus)
+- **OpenAI**: Multiple embedding dimensions, latest GPT models
+- **HuggingFace**: Open-source model support, research-friendly API
+
+### Development
+
+- RSpec test suite with WebMock and VCR
+- RuboCop code style enforcement
+- SimpleCov test coverage reporting
+- Comprehensive documentation
+- Example usage scripts
+- Rake tasks for testing and linting
+
+## [0.0.0] - 2025-08-05
+
+### Added
+
+- Project initialization
+- Basic gem structure
+- Core interfaces defined

data/INTEGRATION_GUIDE.md

@@ -0,0 +1,361 @@
+# AI Providers Integration Guide
+
+This guide explains how to integrate the Prescient gem into an existing Rails AI application.
+
+For the canonical public API and runnable scripts, see the [README](README.md)
+and [examples guide](examples/README.md).
+
+## Integration Steps
+
+### 1. Update Your Gemfile
+
+```ruby
+# Add to your Gemfile
+gem 'prescient', path: './prescient_gem'  # Local development
+# OR when published:
+# gem 'prescient', '~> 0.3.0'
+```
+
+### 2. Replace Existing AI Service
+
+**Before (Original OllamaService):**
+
+```ruby
+# app/services/ollama_service.rb
+class OllamaService
+  def generate_embedding(text)
+    # Direct Ollama API calls
+  end
+
+  def generate_response(prompt, context_items)
+    # Direct Ollama API calls
+  end
+end
+```
+
+**After (Using Prescient):**
+
+```ruby
+# app/services/ai_service.rb
+class AIService
+  def self.client(provider = nil)
+    @clients ||= {}
+    provider_name = provider || Rails.application.config.default_ai_provider
+    @clients[provider_name] ||= Prescient.client(provider_name)
+  end
+
+  def self.generate_embedding(text, provider: nil)
+    client(provider).generate_embedding(text)
+  rescue Prescient::Error => e
+    Rails.logger.error "AI embedding generation failed: #{e.message}"
+    raise
+  end
+
+  def self.generate_response(prompt, context_items = [], provider: nil, **options)
+    client(provider).generate_response(prompt, context_items, **options)
+  rescue Prescient::Error => e
+    Rails.logger.error "AI response generation failed: #{e.message}"
+    raise
+  end
+
+  def self.health_check(provider: nil)
+    client(provider).health_check
+  rescue Prescient::Error => e
+    { status: 'unhealthy', error: e.message }
+  end
+end
+```
+
+### 3. Configuration
+
+**Create initializer:**
+
+```ruby
+# config/initializers/prescient.rb
+Prescient.configure do |config|
+  config.default_provider = Rails.env.production? ? :openai : :ollama
+  config.timeout = 60
+  config.retry_attempts = 3
+  config.retry_delay = 1.0
+
+  # Ollama (Local/Development)
+  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.2:3b'),
+    timeout: 120
+  )
+
+  # OpenAI (Production)
+  if ENV['OPENAI_API_KEY'].present?
+    config.add_provider(:openai, Prescient::Provider::OpenAI,
+      api_key: ENV['OPENAI_API_KEY'],
+      embedding_model: ENV.fetch('OPENAI_EMBEDDING_MODEL', 'text-embedding-3-small'),
+      chat_model: ENV.fetch('OPENAI_CHAT_MODEL', 'gpt-4.1-mini')
+    )
+  end
+
+  # Anthropic (Alternative)
+  if ENV['ANTHROPIC_API_KEY'].present?
+    config.add_provider(:anthropic, Prescient::Provider::Anthropic,
+      api_key: ENV['ANTHROPIC_API_KEY'],
+      model: ENV.fetch('ANTHROPIC_MODEL', 'claude-sonnet-4-20250514')
+    )
+  end
+
+  # HuggingFace (Research/Open Source)
+  if ENV['HUGGINGFACE_API_KEY'].present?
+    config.add_provider(:huggingface, Prescient::Provider::HuggingFace,
+      api_key: ENV['HUGGINGFACE_API_KEY'],
+      embedding_model: ENV.fetch('HUGGINGFACE_EMBEDDING_MODEL', 'sentence-transformers/all-MiniLM-L6-v2'),
+      chat_model: ENV.fetch('HUGGINGFACE_CHAT_MODEL', 'google/gemma-2-2b-it')
+    )
+  end
+end
+
+# Set default provider for Rails
+Rails.application.config.default_ai_provider = :ollama
+```
+
+### 4. Update Environment Variables
+
+```bash
+# .env or environment configuration
+
+# Ollama (Local)
+OLLAMA_URL=http://localhost:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+OLLAMA_CHAT_MODEL=llama3.2:3b
+
+# OpenAI (Production)
+OPENAI_API_KEY=your_openai_api_key
+OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+OPENAI_CHAT_MODEL=gpt-4.1-mini
+
+# Anthropic (Alternative)
+ANTHROPIC_API_KEY=your_anthropic_api_key
+ANTHROPIC_MODEL=claude-sonnet-4-20250514
+
+# HuggingFace (Research)
+HUGGINGFACE_API_KEY=your_huggingface_api_key
+HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
+HUGGINGFACE_CHAT_MODEL=google/gemma-2-2b-it
+```
+
+### 5. Update Controllers
+
+**Before:**
+
+```ruby
+class Api::V1::AiQueriesController < ApplicationController
+  def create
+    embedding = OllamaService.new.generate_embedding(params[:query])
+    # ... rest of the logic
+  end
+end
+```
+
+**After:**
+
+```ruby
+class Api::V1::AiQueriesController < ApplicationController
+  def create
+    # Use default provider or specify one
+    embedding = AIService.generate_embedding(params[:query])
+
+    # Or use specific provider
+    # embedding = AIService.generate_embedding(params[:query], provider: :openai)
+
+    # ... rest of the logic remains the same
+  end
+
+  private
+
+  def generate_ai_response(query, context_items)
+    # Automatically uses configured provider with fallback
+    response = AIService.generate_response(
+      query,
+      context_items,
+      max_tokens: 2000,
+      temperature: 0.7
+    )
+
+    response[:response]
+  rescue Prescient::Error => e
+    Rails.logger.error "AI response failed: #{e.message}"
+    "I apologize, but I'm currently unable to generate a response. Please try again later."
+  end
+end
+```
+
+### 6. Health Check Integration
+
+```ruby
+# app/controllers/api/v1/system/health_controller.rb
+class Api::V1::System::HealthController < ApplicationController
+  def show
+    health_status = {
+      database: database_health,
+      prescient: prescient_health,
+      overall: 'healthy'
+    }
+
+    # Set overall status based on critical components
+    if health_status[:prescient][:primary][:status] != 'healthy'
+      health_status[:overall] = 'degraded'
+    end
+
+    render json: health_status
+  end
+
+  private
+
+  def prescient_health
+    providers = {}
+
+    # Check primary provider
+    primary_provider = Rails.application.config.default_ai_provider
+    providers[:primary] = {
+      name: primary_provider,
+      **AIService.health_check(provider: primary_provider)
+    }
+
+    # Check backup providers
+    backup_providers = [:openai, :anthropic, :huggingface] - [primary_provider]
+    providers[:backups] = backup_providers.map do |provider|
+      {
+        name: provider,
+        **AIService.health_check(provider: provider)
+      }
+    end
+
+    providers
+  end
+
+  def database_health
+    ActiveRecord::Base.connection.execute('SELECT 1')
+    { status: 'healthy' }
+  rescue StandardError => e
+    { status: 'unhealthy', error: e.message }
+  end
+end
+```
+
+### 7. Migration Strategy
+
+1. **Phase 1: Side-by-side deployment**
+
+   - Keep existing OllamaService
+   - Add Prescient alongside
+   - Test thoroughly in development
+
+2. **Phase 2: Gradual migration**
+
+   - Update one controller at a time
+   - Use feature flags to switch between old/new systems
+   - Monitor performance and error rates
+
+3. **Phase 3: Complete migration**
+   - Remove old OllamaService
+   - Update all controllers to use AIService
+   - Clean up unused code
+
+### 8. Testing Updates
+
+```ruby
+# test/services/ai_service_test.rb
+class AIServiceTest < ActiveSupport::TestCase
+  setup do
+    Prescient.configure do |config|
+      config.add_provider(:test, Prescient::Provider::Ollama,
+        url: 'http://localhost:11434',
+        embedding_model: 'test-embed',
+        chat_model: 'test-chat'
+      )
+      config.default_provider = :test
+    end
+  end
+
+  test 'generate_embedding returns an embedding vector' do
+    Prescient.stub(:generate_embedding, [0.1, 0.2, 0.3]) do
+      result = Prescient.generate_embedding('test text', provider: :test, enable_fallback: false)
+      assert_equal [0.1, 0.2, 0.3], result
+    end
+  end
+end
+```
+
+### 9. Monitoring and Logging
+
+```ruby
+# config/initializers/prescient_monitoring.rb
+class PrescientMonitoring
+  def self.setup!
+    ActiveSupport::Notifications.subscribe('prescient.request') do |name, start, finish, id, payload|
+      duration = finish - start
+
+      Rails.logger.info "AI Provider Request: #{payload[:provider]} - #{payload[:operation]} - #{duration.round(3)}s"
+
+      # Send metrics to your monitoring system
+      # StatsD.increment('prescient.requests', tags: [
+      #   "provider:#{payload[:provider]}",
+      #   "operation:#{payload[:operation]}",
+      #   "status:#{payload[:status]}"
+      # ])
+    end
+  end
+end
+
+PrescientMonitoring.setup! if Rails.env.production?
+```
+
+### 10. Performance Optimization
+
+```ruby
+# app/services/ai_service.rb (enhanced)
+class AIService
+  # Connection pooling for providers
+  def self.client(provider = nil)
+    @clients ||= {}
+    provider_name = provider || Rails.application.config.default_ai_provider
+
+    @clients[provider_name] ||= begin
+      # Use connection pooling for high-traffic applications
+      Prescient.client(provider_name)
+    end
+  end
+
+  # Caching for embeddings (optional)
+  def self.generate_embedding(text, provider: nil)
+    cache_key = "ai_embedding:#{ Digest::SHA256.hexdigest(text)}:#{ provider}"
+
+    Rails.cache.fetch(cache_key, expires_in: 1.hour) do
+      client(provider).generate_embedding(text)
+    end
+  rescue Prescient::Error => e
+    Rails.logger.error "AI embedding generation failed: #{e.message}"
+    raise
+  end
+end
+```
+
+## Benefits of Migration
+
+1. **Provider Flexibility**: Easy switching between AI providers
+2. **Fallback Support**: Automatic fallback to backup providers
+3. **Better Error Handling**: Comprehensive error classification
+4. **Monitoring**: Built-in health checks and metrics
+5. **Testing**: Easier mocking and testing
+6. **Scalability**: Better support for different deployment scenarios
+7. **Cost Optimization**: Use local models for development, cloud for production
+
+## Rollback Plan
+
+If issues arise, quickly rollback by:
+
+1. Revert initializer changes
+2. Switch controllers back to OllamaService
+3. Deploy previous version
+4. Debug issues separately
+
+The gem structure allows for easy rollback since it's designed as a drop-in replacement.

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Ken C. Demanawa
+Copyright (c) 2025 Kenneth C. Demanawa
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal