prescient 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f12c7d49067ef7917aa1f674f83e4ff8111a5606fa62edcbb7c97b8791dfbee
-  data.tar.gz: 4bf6ad2a1a8988ec7eb77cb5a2e278f902ceaa2cfc30d0de3c303c4fa1017168
+  metadata.gz: 167f50351b78b35d1ae63d3487285db48c07799ad015b5d49f46dd3c451afa49
+  data.tar.gz: 91e1895635015120c75b0b461fea017d8ec7c4b5ebd81f1d2b0c86ba37690e1d
 SHA512:
-  metadata.gz: b0fd6efd2a47ce4ffd2766d32706b4b852bfb4e47b62b10ca5e39b50698281048d15be905cfcace617185958194bd1fccde939fd4bac1d83d617cf72707a54c5
-  data.tar.gz: dfeb2ac6ed61f430730c589a42853b0d118cb425871784dc481e6ea781fedbfd6fcd3582cdadf89718b01c97a2da234898b8bbd868fc709ce3582c02e0662bee
+  metadata.gz: 6cdf4ed9b05525692898cdd88153f092c23f5caac1d422962bdc768055bb225e960e45a9fb877adb17a7c686e8bf608db09dea1b3e24ebc15767071255910285
+  data.tar.gz: ecec27b8c215dfe5fb92e00f68fd6a5ae66c8284342525c9ae635214318032fc4970a72d2944679e455915f2ba8de8425a07706530ca6c309bedc5d5d4ff114a

data/.dockerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.ignoreme
+.bundle
+.yardoc
+_yardoc
+coverage
+doc
+tmp
+test
+spec
+examples/*.rb
+*.gem
+.env*
+AGENTS.md
+Dockerfile.example
+docker-compose.yml
+docker-compose.api.yml

data/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ## Unreleased
 
+## [0.6.0] - 2025-08-15
+
+### Added
+
+- Added a dependency-free Rack-compatible REST API with generation, embeddings,
+  bounded batch embeddings, provider/model discovery, capabilities, health,
+  liveness, readiness, version, request IDs, authentication hooks, and JSON
+  error envelopes.
+- Added a small Rack example that lists the REST API endpoints and delegates
+  requests to `Prescient::API`.
+- Added an optional `rack_example` bundle group with Rack, Rackup, and Puma for
+  running the example application without adding web-server dependencies to
+  the library.
+- Added a non-root, healthchecked Docker image and Compose example for the REST
+  API, with optional GHCR publication on version tags.
+- Documented mounting `Prescient::API` in Rails routes with its endpoint
+  catalog and authentication example.
+- Made the CLI and REST API optional lazy-loaded entry points so library users
+  requiring only `prescient` do not load either interface eagerly.
+
+## [0.5.0] - 2025-08-14
+
+### Added
+
+- Added a versioned YAML configuration loader with environment-variable references,
+  configuration validation, precedence rules, and a packaged JSON Schema.
+- Added YAML-configurable prompt templates and CLI prompt overrides, including
+  support for loading multiline templates from a file.
+- Added `prescient config example` for generating an annotated schema-backed YAML configuration starter.
+- Added Google Gemini provider support for text generation, embeddings, health checks, and model listing.
+- Added Gemini environment-variable defaults and YAML configuration support.
+- Added Mistral provider support for text generation, embeddings, health checks, and model listing.
+- Added Mistral environment-variable defaults and YAML configuration support.
+- Added DeepSeek provider support for text generation, health checks, and model listing.
+- Documented DeepSeek's unsupported embedding capability explicitly.
+- Added xAI provider support for text generation, health checks, and model listing.
+- Documented xAI's unsupported embedding capability explicitly.
+
+### Changed
+
+- Raised YARD documentation coverage enforcement from 99% to 100%.
+
 ## [0.4.0] - 2025-08-14
 
 ### Added

data/Dockerfile

@@ -0,0 +1,45 @@
+# syntax=docker/dockerfile:1
+
+FROM ruby:3.3-alpine AS builder
+
+WORKDIR /app
+
+RUN apk add --no-cache build-base git
+
+ENV BUNDLE_WITH=rack_example \
+    BUNDLE_WITHOUT=development:test \
+    BUNDLE_PATH=/usr/local/bundle
+
+COPY Gemfile prescient.gemspec ./
+COPY lib ./lib
+
+RUN bundle install --jobs 4 --retry 3
+
+FROM ruby:3.3-alpine
+
+WORKDIR /app
+
+RUN apk add --no-cache curl tzdata && \
+    addgroup -S -g 1000 prescient && \
+    adduser -S -u 1000 -G prescient prescient
+
+ENV BUNDLE_WITH=rack_example \
+    BUNDLE_WITHOUT=development:test \
+    BUNDLE_PATH=/usr/local/bundle \
+    GEM_HOME=/usr/local/bundle/ruby/3.3.0 \
+    GEM_PATH=/usr/local/bundle/ruby/3.3.0 \
+    PATH=/usr/local/bundle/ruby/3.3.0/bin:/usr/local/bundle/bin:$PATH \
+    RACK_ENV=production
+
+COPY --from=builder /usr/local/bundle /usr/local/bundle
+COPY --chown=prescient:prescient lib ./lib
+COPY --chown=prescient:prescient examples/rest_api.ru ./examples/rest_api.ru
+
+USER prescient
+
+EXPOSE 9292
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl --fail --silent http://127.0.0.1:9292/healthz || exit 1
+
+CMD ["rackup", "-s", "puma", "-o", "0.0.0.0", "-p", "9292", "/app/examples/rest_api.ru"]

data/INTEGRATION_GUIDE.md

@@ -11,9 +11,7 @@ and [examples guide](examples/README.md).
 
 ```ruby
 # Add to your Gemfile
-gem 'prescient', path: './prescient_gem'  # Local development
-# OR when published:
-# gem 'prescient', '~> 0.4.0'
+gem 'prescient', '~> 0.6.0'
 ```
 
 ### 2. Replace Existing AI Service
@@ -111,13 +109,107 @@ Prescient.configure do |config|
       chat_model: ENV.fetch('HUGGINGFACE_CHAT_MODEL', 'google/gemma-2-2b-it')
     )
   end
+
+  # Google Gemini
+  if ENV['GEMINI_API_KEY'].present?
+    config.add_provider(:gemini, Prescient::Provider::Gemini,
+      api_key: ENV['GEMINI_API_KEY'],
+      embedding_model: ENV.fetch('GEMINI_EMBEDDING_MODEL', 'gemini-embedding-001'),
+      chat_model: ENV.fetch('GEMINI_CHAT_MODEL', 'gemini-2.5-flash')
+    )
+  end
+
+  # Mistral
+  if ENV['MISTRAL_API_KEY'].present?
+    config.add_provider(:mistral, Prescient::Provider::Mistral,
+      api_key: ENV['MISTRAL_API_KEY'],
+      embedding_model: ENV.fetch('MISTRAL_EMBEDDING_MODEL', 'mistral-embed'),
+      chat_model: ENV.fetch('MISTRAL_CHAT_MODEL', 'mistral-large-latest')
+    )
+  end
+
+  # DeepSeek supports generation, but not embeddings.
+  if ENV['DEEPSEEK_API_KEY'].present?
+    config.add_provider(:deepseek, Prescient::Provider::DeepSeek,
+      api_key: ENV['DEEPSEEK_API_KEY'],
+      chat_model: ENV.fetch('DEEPSEEK_CHAT_MODEL', 'deepseek-v4-flash')
+    )
+  end
+
+  # xAI supports generation, but not embeddings.
+  if ENV['XAI_API_KEY'].present?
+    config.add_provider(:xai, Prescient::Provider::XAI,
+      api_key: ENV['XAI_API_KEY'],
+      chat_model: ENV.fetch('XAI_CHAT_MODEL', 'grok-4.5')
+    )
+  end
 end
 
 # Set default provider for Rails
 Rails.application.config.default_ai_provider = :ollama
 ```
 
-### 4. Update Environment Variables
+For YAML-based deployments, use the versioned configuration format and keep
+credentials in environment variables:
+
+```ruby
+Prescient.load_configuration('prescient.yml')
+```
+
+Configuration precedence is CLI overrides, environment defaults and
+references, YAML values, then built-in defaults. The generated
+`prescient config example` file includes the current JSON Schema URL.
+
+### 4. Mount the REST API
+
+`Prescient::API` is Rack-compatible and can be mounted directly in a Rails
+route set. The API keeps provider execution on `Prescient::Client` and exposes
+only generic operations:
+
+```ruby
+# config/routes.rb
+prescient_api = Prescient::API.new(
+  authentication: lambda { |env|
+    expected_token = ENV.fetch('PRESCIENT_API_TOKEN', nil)
+    expected_token && env['HTTP_AUTHORIZATION'] == "Bearer #{expected_token}"
+  }
+)
+
+mount prescient_api => '/prescient', as: :prescient_api
+```
+
+This makes the following routes available under `/prescient`:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/healthz` | Liveness check |
+| `GET` | `/readyz` | Readiness check |
+| `GET` | `/v1/version` | Library and API versions |
+| `GET` | `/v1/providers` | Configured providers |
+| `GET` | `/v1/models` | Available models, optionally filtered by provider |
+| `GET` | `/v1/capabilities` | Provider capabilities |
+| `GET` | `/v1/health` | Provider health |
+| `POST` | `/v1/generate` | Text generation |
+| `POST` | `/v1/embeddings` | Single embedding |
+| `POST` | `/v1/embeddings/batch` | Bounded batch embeddings |
+
+For example:
+
+```bash
+curl http://localhost:3000/prescient/healthz
+
+curl -X POST http://localhost:3000/prescient/v1/generate \
+  -H "Authorization: Bearer ${PRESCIENT_API_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"Explain Ruby fibers"}'
+```
+
+Responses include a request ID. Request bodies are size-limited, batch inputs
+are bounded, and JSON errors do not expose raw provider response bodies. Keep
+the API behind the application’s normal TLS, authentication, rate-limiting,
+and observability controls.
+
+### 5. Update Environment Variables
 
 ```bash
 # .env or environment configuration
@@ -140,9 +232,27 @@ ANTHROPIC_MODEL=claude-sonnet-4-20250514
 HUGGINGFACE_API_KEY=your_huggingface_api_key
 HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 HUGGINGFACE_CHAT_MODEL=google/gemma-2-2b-it
+
+# Google Gemini
+GEMINI_API_KEY=your_gemini_api_key
+GEMINI_EMBEDDING_MODEL=gemini-embedding-001
+GEMINI_CHAT_MODEL=gemini-2.5-flash
+
+# Mistral
+MISTRAL_API_KEY=your_mistral_api_key
+MISTRAL_EMBEDDING_MODEL=mistral-embed
+MISTRAL_CHAT_MODEL=mistral-large-latest
+
+# DeepSeek (generation only)
+DEEPSEEK_API_KEY=your_deepseek_api_key
+DEEPSEEK_CHAT_MODEL=deepseek-v4-flash
+
+# xAI (generation only)
+XAI_API_KEY=your_xai_api_key
+XAI_CHAT_MODEL=grok-4.5
 ```
 
-### 5. Update Controllers
+### 6. Update Controllers
 
 **Before:**
 
@@ -188,7 +298,7 @@ class Api::V1::AiQueriesController < ApplicationController
 end
 ```
 
-### 6. Health Check Integration
+### 7. Health Check Integration
 
 ```ruby
 # app/controllers/api/v1/system/health_controller.rb
@@ -221,7 +331,7 @@ class Api::V1::System::HealthController < ApplicationController
     }
 
     # Check backup providers
-    backup_providers = [:openai, :anthropic, :huggingface] - [primary_provider]
+    backup_providers = %i[openai anthropic huggingface gemini mistral deepseek xai] - [primary_provider]
     providers[:backups] = backup_providers.map do |provider|
       {
         name: provider,
@@ -241,7 +351,7 @@ class Api::V1::System::HealthController < ApplicationController
 end
 ```
 
-### 7. Migration Strategy
+### 8. Migration Strategy
 
 1. **Phase 1: Side-by-side deployment**
 
@@ -260,7 +370,7 @@ end
    - Update all controllers to use AIService
    - Clean up unused code
 
-### 8. Testing Updates
+### 9. Testing Updates
 
 ```ruby
 # test/services/ai_service_test.rb
@@ -285,7 +395,7 @@ class AIServiceTest < ActiveSupport::TestCase
 end
 ```
 
-### 9. Monitoring and Logging
+### 10. Monitoring and Logging
 
 ```ruby
 # config/initializers/prescient_monitoring.rb
@@ -309,7 +419,7 @@ end
 PrescientMonitoring.setup! if Rails.env.production?
 ```
 
-### 10. Performance Optimization
+### 11. Performance Optimization
 
 ```ruby
 # app/services/ai_service.rb (enhanced)