prescient 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2b41fc6acb2528a3d74e5bbc58f777a34ead604d3f7bc4e58cc1ff4f8709142
-  data.tar.gz: 665efb1e4b6cc1ed526e91470e7c06278461e98e9d81f0ace34b0872c456251f
+  metadata.gz: a54256e23ba55fc2492fae38d687b275dcb2362df73449d3212bd03659150717
+  data.tar.gz: 73ab805b7a5781a1d03488605ae8d7890feda7344b41b1ac550343484b3b597a
 SHA512:
-  metadata.gz: 23eeca8c5353bcb4219a634905a7f6dc565acbfde665e0e71a0682eb3277abb9384882f70afe168ee27c435f049048f0a715b92daac3fcdc8f34f4ff2b4f7de0
-  data.tar.gz: 77eccf05a9bedfad68de0a262b4ebf32d35b1c1a6d4c35f0327c1c6d16814841a6361b5123b27a8ba6f05e9d999256e2b330200d3e4c7eda0763010c98759c44
+  metadata.gz: e918a87b3e09affe9d5a002a3955051e7729ee565f84c42c534c99dc3fc70371fda930e63cc90801da07b4c4f5e48031c41e952088dfc3de24f0f38b579e9567
+  data.tar.gz: feb707947b7cc0b67d8bff933b4c584a69595b9b5e1dd3f214b4c4aa2d48c0577c996b542c238fbcef337f0f276a1bb995acc9653e8fad32262a6f6fa17caaf4

data/.rubocop.yml

@@ -11,10 +11,8 @@ plugins:
 AllCops:
   # Target Ruby 3.1+ (matches gemspec requirement)
   TargetRubyVersion: 3.1
-
   # Use new cops by default
   NewCops: enable
-
   # Exclude common directories
   Exclude:
     - 'vendor/**/*'

data/.yardopts

@@ -1,10 +1,7 @@
---markup markdown
---markup-provider kramdown
---main README.md
---output-dir doc
+--title "Prescient API Documentation"
 --protected
---private
---title "Prescient Documentation"
+--markup markdown
+
 lib/**/*.rb
 -
 README.md

data/CHANGELOG.md

@@ -1,11 +1,48 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## Unreleased
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.3.0] - 2025-08-14
 
-## [0.1.0] - 2025-08-05
+### 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
 

data/INTEGRATION_GUIDE.md

@@ -1,6 +1,9 @@
 # AI Providers Integration Guide
 
-This guide explains how to integrate the AI Providers gem into your existing Rails AI application.
+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
 
@@ -10,7 +13,7 @@ This guide explains how to integrate the AI Providers gem into your existing Rai
 # Add to your Gemfile
 gem 'prescient', path: './prescient_gem'  # Local development
 # OR when published:
-# gem 'prescient', '~> 0.1.0'
+# gem 'prescient', '~> 0.3.0'
 ```
 
 ### 2. Replace Existing AI Service
@@ -30,7 +33,7 @@ class OllamaService
 end
 ```
 
-**After (Using AI Providers Gem):**
+**After (Using Prescient):**
 
 ```ruby
 # app/services/ai_service.rb
@@ -76,36 +79,36 @@ Prescient.configure do |config|
   config.retry_delay = 1.0
 
   # Ollama (Local/Development)
-  config.add_provider(:ollama, Prescient::Ollama::Provider,
+  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'),
+    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::OpenAI::Provider,
+    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-3.5-turbo')
+      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::Anthropic::Provider,
+    config.add_provider(:anthropic, Prescient::Provider::Anthropic,
       api_key: ENV['ANTHROPIC_API_KEY'],
-      model: ENV.fetch('ANTHROPIC_MODEL', 'claude-3-haiku-20240307')
+      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::HuggingFace::Provider,
+    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', 'microsoft/DialoGPT-medium')
+      chat_model: ENV.fetch('HUGGINGFACE_CHAT_MODEL', 'google/gemma-2-2b-it')
     )
   end
 end
@@ -122,21 +125,21 @@ Rails.application.config.default_ai_provider = :ollama
 # Ollama (Local)
 OLLAMA_URL=http://localhost:11434
 OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-OLLAMA_CHAT_MODEL=llama3.1:8b
+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-3.5-turbo
+OPENAI_CHAT_MODEL=gpt-4.1-mini
 
 # Anthropic (Alternative)
 ANTHROPIC_API_KEY=your_anthropic_api_key
-ANTHROPIC_MODEL=claude-3-haiku-20240307
+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=microsoft/DialoGPT-medium
+HUGGINGFACE_CHAT_MODEL=google/gemma-2-2b-it
 ```
 
 ### 5. Update Controllers
@@ -243,7 +246,7 @@ end
 1. **Phase 1: Side-by-side deployment**
 
    - Keep existing OllamaService
-   - Add AI Providers gem alongside
+   - Add Prescient alongside
    - Test thoroughly in development
 
 2. **Phase 2: Gradual migration**
@@ -260,11 +263,11 @@ end
 ### 8. Testing Updates
 
 ```ruby
-# spec/services/ai_service_spec.rb
-RSpec.describe AIService do
-  before do
+# test/services/ai_service_test.rb
+class AIServiceTest < ActiveSupport::TestCase
+  setup do
     Prescient.configure do |config|
-      config.add_provider(:test, Prescient::Ollama::Provider,
+      config.add_provider(:test, Prescient::Provider::Ollama,
         url: 'http://localhost:11434',
         embedding_model: 'test-embed',
         chat_model: 'test-chat'
@@ -273,15 +276,10 @@ RSpec.describe AIService do
     end
   end
 
-  describe '.generate_embedding' do
-    it 'returns embedding vector' do
-      # Mock the provider response
-      allow_any_instance_of(Prescient::Ollama::Provider)
-        .to receive(:generate_embedding)
-        .and_return([0.1, 0.2, 0.3])
-
-      result = described_class.generate_embedding('test text')
-      expect(result).to eq([0.1, 0.2, 0.3])
+  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

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