prescient 0.4.0 → 0.6.0

data/README.md

@@ -1,6 +1,12 @@
 # Prescient
 
-Prescient is a boring AI provider abstraction for Ruby. Configure your AI providers once, then use the same interface regardless of whether the request is handled by OpenAI, Anthropic, Ollama, or Hugging Face. Prescient handles provider selection, retries, health checks, and fallback.
+[![Gem Version](https://img.shields.io/gem/v/prescient?logo=rubygems&logoColor=white)](https://rubygems.org/gems/prescient)
+[![Requires Ruby 3.1+](https://img.shields.io/badge/Requires-Ruby%203.1%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![CI](https://github.com/kanutocd/prescient/actions/workflows/ci.yml/badge.svg)](https://github.com/kanutocd/prescient/actions/workflows/ci.yml)
+[![Security](https://img.shields.io/github/actions/workflow/status/kanutocd/prescient/security.yml?branch=main&event=push&label=Security)](https://github.com/kanutocd/prescient/actions/workflows/security.yml)
+[![License](https://img.shields.io/badge/License-MIT-22C55E)](LICENSE.txt)
+
+Prescient is a boring AI provider abstraction for Ruby. Configure your AI providers once, then use the same interface regardless of whether the request is handled by OpenAI, Anthropic, Ollama, Hugging Face, Google Gemini, Mistral, DeepSeek, or xAI. Prescient handles provider selection, retries, health checks, and fallback.
 
 For focused guidance, see the **[examples guide](https://github.com/kanutocd/prescient/tree/main/examples)**,
 **[Rails integration guide](https://github.com/kanutocd/prescient/blob/main/INTEGRATION_GUIDE.md)**, and
@@ -14,7 +20,7 @@ For focused guidance, see the **[examples guide](https://github.com/kanutocd/pre
 - **Text Completion**: Chat completions with context support
 - **Error Handling**: Robust error handling with automatic retries
 - **Health Monitoring**: Built-in health checks for all providers
-- **Flexible Configuration**: Environment variable and programmatic configuration
+- **Flexible Configuration**: YAML, environment variable, and programmatic configuration
 
 ## Supported Providers
 
@@ -42,6 +48,30 @@ For focused guidance, see the **[examples guide](https://github.com/kanutocd/pre
 - **Capabilities**: Embeddings, Text Generation
 - **Use Case**: Open-source models, research
 
+### Google Gemini
+
+- **Models**: Gemini generation and embedding models
+- **Capabilities**: Embeddings, Text Generation, Model Listing
+- **Use Case**: Google AI hosted models
+
+### Mistral
+
+- **Models**: Mistral chat and embedding models
+- **Capabilities**: Embeddings, Text Generation, Model Listing
+- **Use Case**: Mistral AI hosted models
+
+### DeepSeek
+
+- **Models**: DeepSeek chat models
+- **Capabilities**: Text Generation, Model Listing (no embeddings)
+- **Use Case**: DeepSeek hosted reasoning and chat models
+
+### xAI
+
+- **Models**: Grok chat models
+- **Capabilities**: Text Generation, Model Listing (no embeddings)
+- **Use Case**: xAI hosted reasoning and chat models
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -70,6 +100,7 @@ Prescient includes a thin CLI for provider inspection and common operations:
 prescient providers
 prescient health
 prescient config validate
+prescient config example
 prescient generate "Explain Ruby Ractors"
 prescient embed "Ruby is a programming language"
 ```
@@ -81,6 +112,13 @@ Supported options include:
 --model NAME             Override the selected operation's model
 --chat-model NAME        Override the chat model for generation
 --embedding-model NAME   Override the embedding model
+--system-prompt TEXT     Override the system prompt
+--no-context-template TEXT
+                         Override the no-context prompt template
+--with-context-template TEXT
+                         Override the with-context prompt template
+--prompt-templates-file PATH
+                         Load prompt templates from a YAML file
 --api-key KEY            Use an API key for the operation
 --api-key-env NAME       Read the API key from an environment variable
 --format FORMAT          Select text or json output
@@ -96,7 +134,7 @@ printf '%s' "Explain PostgreSQL logical replication" | \
   prescient generate --provider openai --format json
 ```
 
-Example JSON output:
+OpenAI example JSON output:
 
 ```json
 {
@@ -125,6 +163,35 @@ Example JSON output:
 }
 ```
 
+Anthropic example JSON output:
+
+```json
+{
+    "response": "PostgreSQL logical replication is a method of replicating data between PostgreSQL databases that allows fine-grained control over which data is replicated and how it is applied. Unlike physical replication, which copies the entire database cluster at the storage level, logical replication works at the level of individual database changes, such as INSERT, UPDATE, and DELETE operations.\n\n### Key Features of PostgreSQL Logical Replication:\n\n1. **Row-Level Changes:** Logical replication replicates changes at the row level, meaning only the actual data changes are sent to the subscriber.\n\n2. **Selective Replication:** You can replicate specific tables rather than the entire database. This allows partial replication tailored to your needs.\n\n3. **Asynchronous Replication:** Logical replication is asynchronous, so there might be a slight delay between the publisher and subscriber.\n\n4. **Bidirectional Replication (with care):** While PostgreSQL does not natively support multi-master replication, logical replication can be configured to allow bidirectional replication setups with caution to avoid conflicts.\n\n5. **Decoupling of Replication:** Logical replication decouples the replication from the physical storage, enabling replication across different PostgreSQL versions (within compatibility limits).\n\n### How Logical Replication Works:\n\n- **Publisher:** The source database that sends changes. It publishes a set of changes based on one or more publications.\n- **Publication:** A set of changes (typically from specific tables) that the publisher makes available to subscribers.\n- **Subscriber:** The target database that receives changes and applies them.\n- **Subscription:** A configuration on the subscriber that connects to a publication and applies changes.\n\n### Use Cases:\n\n- Replicating specific tables or subsets of data.\n- Migrating data between PostgreSQL versions or clusters.\n- Distributing data geographically.\n- Implementing data warehousing or reporting solutions with up-to-date data.\n- Supporting microservices architectures where different services own different parts of the data.\n\n### Basic Setup Example:\n\n1. **On the Publisher:**\n\n```sql\nCREATE PUBLICATION my_publication FOR TABLE my_table;\n```\n\n2. **On the Subscriber:**\n\n```sql\nCREATE SUBSCRIPTION my_subscription\nCONNECTION 'host=publisher_host dbname=mydb user=replicator password=secret'\nPUBLICATION my_publication;\n```\n\nOnce set up, changes to `my_table` on the publisher will be sent and applied to the subscriber.\n\n### Important Notes:\n\n- Logical replication requires WAL (Write-Ahead Logging) to be configured properly with `wal_level = logical`.\n- Some DDL changes (like adding columns) need careful handling as logical replication primarily replicates DML changes.\n- Logical replication does not replicate sequences, large objects, or certain system catalogs automatically.\n- Conflict resolution is mostly manual; the subscriber applies changes as received.\n\n---\n\nIn summary, PostgreSQL logical replication provides a flexible, table-level replication mechanism that supports selective and version-independent replication of data changes, suitable for many modern replication and data distribution scenarios.",
+    "model": "gpt-4.1-mini",
+    "provider": "openai",
+    "processing_time": null,
+    "metadata": {
+        "usage": {
+            "prompt_tokens": 38,
+            "completion_tokens": 597,
+            "total_tokens": 635,
+            "prompt_tokens_details": {
+                "cached_tokens": 0,
+                "audio_tokens": 0
+            },
+            "completion_tokens_details": {
+                "reasoning_tokens": 0,
+                "audio_tokens": 0,
+                "accepted_prediction_tokens": 0,
+                "rejected_prediction_tokens": 0
+            }
+        },
+        "finish_reason": "stop"
+    }
+}
+```
+
 For automated model and credential overrides:
 
 ```bash
@@ -146,6 +213,72 @@ The CLI writes results to stdout, diagnostics to stderr, and returns a
 non-zero status for invalid usage, provider errors, or unreachable health
 checks. It uses the same `Prescient::Client` execution path as Ruby callers.
 
+Generate a schema-backed, annotated starter configuration with:
+
+```bash
+prescient config example > prescient.yml
+```
+
+The generated file points YAML language servers at the latest schema on the
+main branch. Pin the schema URL to a release tag when reproducible tooling is
+required.
+
+## REST API
+
+`Prescient::API` is a dependency-free Rack-compatible application. Mount it in
+the web server of your choice without making HTTP a requirement for library
+users. The API and CLI files are loaded lazily; `Prescient::API` autoloads on
+first reference, or you can require it explicitly:
+
+```ruby
+require 'prescient'
+require 'prescient/api'
+
+run Prescient::API.new(
+  authentication: ->(env) { env['HTTP_AUTHORIZATION'] == "Bearer #{ENV['PRESCIENT_API_TOKEN']}" }
+)
+```
+
+Available endpoints include:
+
+- **`POST /v1/generate`**
+- **`POST /v1/embeddings`**
+- **`POST /v1/embeddings/batch`**
+- **`GET /v1/providers`**
+- **`GET /v1/models`**
+- **`GET /v1/capabilities`**
+- **`GET /v1/health`**
+- **`GET /v1/version`**
+- **`GET /healthz`**
+- **`GET /readyz`**
+
+Responses include:
+
+- a request ID
+- a generic JSON error envelope that never exposes raw provider response bodies.
+
+## Docker
+
+Build and run the REST API image as a non-root container:
+
+```bash
+docker build -t prescient:local .
+docker run --rm -p 9292:9292 \
+  -e PRESCIENT_API_TOKEN=change-me \
+  prescient:local
+```
+
+The image exposes port `9292`, includes a `/healthz` healthcheck, supports a
+read-only filesystem, and does not bundle PostgreSQL, Redis, or a worker. The
+Compose example provides the same setup:
+
+```bash
+PRESCIENT_API_TOKEN=change-me docker compose -f docker-compose.api.yml up --build
+```
+
+Tagged releases publish to GHCR as:
+`ghcr.io/kanutocd/prescient:<version>`.
+
 ## Configuration
 
 ### Environment Variables
@@ -169,6 +302,68 @@ OPENAI_CHAT_MODEL=gpt-4.1-mini
 HUGGINGFACE_API_KEY=your_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_api_key
+GEMINI_EMBEDDING_MODEL=gemini-embedding-001
+GEMINI_CHAT_MODEL=gemini-2.5-flash
+
+# Mistral
+MISTRAL_API_KEY=your_api_key
+MISTRAL_EMBEDDING_MODEL=mistral-embed
+MISTRAL_CHAT_MODEL=mistral-large-latest
+
+# DeepSeek
+DEEPSEEK_API_KEY=your_api_key
+DEEPSEEK_CHAT_MODEL=deepseek-v4-flash
+
+# xAI
+XAI_API_KEY=your_api_key
+XAI_CHAT_MODEL=grok-4.5
+```
+
+### YAML Configuration
+
+Load a versioned YAML configuration with environment-backed credentials:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/kanutocd/prescient/refs/heads/main/schema/prescient.configuration.schema.json
+version: 1
+default_provider: openai
+providers:
+  openai:
+    type: openai
+    api_key_env: OPENAI_API_KEY
+    embedding_model: text-embedding-3-small
+    chat_model: gpt-4.1-mini
+```
+
+```ruby
+Prescient.load_configuration('prescient.yml')
+```
+
+Configuration precedence is CLI overrides, environment defaults and references,
+YAML values, then built-in defaults. Use `prescient config validate` to check a
+configuration before running an operation, or `prescient config example` to
+generate an annotated starter file.
+
+Prompt templates can also be configured per provider. Use the YAML mapping for
+multiline templates, or pass a template file to a single CLI operation:
+
+```yaml
+providers:
+  openai:
+    type: openai
+    api_key_env: OPENAI_API_KEY
+    chat_model: gpt-4.1-mini
+    prompt_templates:
+      system_prompt: You are a concise assistant.
+      no_context_template: "%{system_prompt}\n\nUser: %{query}"
+      with_context_template: "%{system_prompt}\n\nContext:\n%{context}\n\nUser: %{query}"
+```
+
+```bash
+prescient generate --prompt-templates-file prompts.yml "Summarize this"
 ```
 
 ### Programmatic Configuration
@@ -202,6 +397,32 @@ Prescient.configure do |config|
     embedding_model: 'text-embedding-3-small',
     chat_model: 'gpt-4.1-mini'
   )
+
+  # Add Google Gemini
+  config.add_provider(:gemini, Prescient::Provider::Gemini,
+    api_key: ENV['GEMINI_API_KEY'],
+    embedding_model: 'gemini-embedding-001',
+    chat_model: 'gemini-2.5-flash'
+  )
+
+  # Add Mistral
+  config.add_provider(:mistral, Prescient::Provider::Mistral,
+    api_key: ENV['MISTRAL_API_KEY'],
+    embedding_model: 'mistral-embed',
+    chat_model: 'mistral-large-latest'
+  )
+
+  # Add DeepSeek
+  config.add_provider(:deepseek, Prescient::Provider::DeepSeek,
+    api_key: ENV['DEEPSEEK_API_KEY'],
+    chat_model: 'deepseek-v4-flash'
+  )
+
+  # Add xAI
+  config.add_provider(:xai, Prescient::Provider::XAI,
+    api_key: ENV['XAI_API_KEY'],
+    chat_model: 'grok-4.5'
+  )
 end
 ```
 
@@ -357,14 +578,14 @@ Prescient.configure do |config|
     prompt_templates: {
       system_prompt: 'You are a friendly customer service representative.',
       no_context_template: <<~TEMPLATE.strip,
-        %{ system_prompt }
+        %{system_prompt}
 
         Customer Question: %{query}
 
         Please provide a helpful response.
       TEMPLATE
       with_context_template: <<~TEMPLATE.strip
-        %{ system_prompt } Use the company info below to help answer.
+        %{system_prompt} Use the company info below to help answer.
 
         Company Information:
         %{context}
@@ -534,8 +755,9 @@ results = store.search(embedding:, provider: :openai, model: 'text-embedding-3-s
 ```
 
 Every vector must exactly match the store's configured dimensions; Prescient
-never pads or truncates vectors. The existing application-schema example below
-remains available for projects that need documents, chunks, and custom metadata.
+never pads or truncates vectors. The application-schema example below is
+optional integration material for projects that need documents, chunks, and
+custom metadata; it is not managed by `Prescient::Pgvector::Store`.
 
 ### Setup with Docker
 
@@ -554,7 +776,7 @@ docker compose up -d postgres
 
 ### Database Schema
 
-The setup creates these key tables:
+The optional Docker demo creates these application-owned tables:
 
 - **`documents`** - Store original content and metadata
 - **`document_embeddings`** - Store vector embeddings for documents
@@ -736,10 +958,9 @@ DB_HOST=localhost ruby examples/vector_search.rb
 
 The example demonstrates:
 
-- Document embedding generation and storage
-- Similarity search with different distance functions
-- Metadata filtering and advanced queries
-- Performance comparison between approaches
+- Embedding generation through `Prescient::Client`
+- Dimension-validated storage through `Prescient::Pgvector::Store`
+- Similarity search with provider and model filters
 
 ## Advanced Usage
 
@@ -813,6 +1034,30 @@ puts info[:options]   # => { ... } (excluding sensitive data)
 - Research-friendly
 - Free tier available
 
+### Google Gemini
+
+- Text generation and embeddings
+- Google AI API integration
+- Model discovery through the Gemini models endpoint
+
+### Mistral
+
+- Text generation and embeddings
+- OpenAI-compatible API style
+- Model discovery through the Mistral models endpoint
+
+### DeepSeek
+
+- Text generation
+- OpenAI-compatible API style
+- No embedding support
+
+### xAI
+
+- Text generation
+- OpenAI-compatible API style
+- No embedding support
+
 ## Docker Setup (Recommended for Ollama)
 
 The easiest way to get started with Prescient and Ollama is using Docker Compose:
@@ -1045,10 +1290,10 @@ OPENAI_API_KEY=... \
 bundle exec ruby -Itest test/prescient/live_provider_smoke_test.rb
 ```
 
-Supported provider names are `ollama`, `anthropic`, `openai`, and
-`huggingface`. The corresponding provider environment variables and model
-overrides are honored. These tests are never live unless both opt-in
-variables are set.
+Supported provider names are `ollama`, `anthropic`, `openai`, `huggingface`,
+`gemini`, `mistral`, `deepseek`, and `xai`. The corresponding provider
+environment variables and model overrides are honored. These tests are never
+live unless both opt-in variables are set.
 
 ### RBS and Steep
 

data/Rakefile

@@ -32,7 +32,7 @@ namespace :yard do
     abort("Unable to determine YARD coverage") unless match
 
     coverage = match[1].to_f
-    minimum = 99.0
+    minimum = 100.0
     if coverage < minimum
       message = format(
         "YARD coverage %<coverage>.2f%% is below %<minimum>.2f%%",

data/VECTOR_SEARCH_GUIDE.md

@@ -27,6 +27,10 @@ store.create_index!(metric: :cosine)
 or chunk tables, connections, migrations outside that table, or the `pg` gem.
 Use `#upsert` and `#search` with embeddings of exactly the configured dimension.
 
+The remaining sections describe an optional application-owned document schema
+used by the repository's Docker demo. They are not tables created or managed
+by `Prescient::Pgvector::Store`.
+
 ### 1. Start Services
 
 ```bash
@@ -55,12 +59,12 @@ export DB_HOST=localhost
 export OLLAMA_URL=http://localhost:11434
 
 # Run the example
-ruby examples/vector_search.rb
+bundle exec ruby examples/vector_search.rb
 ```
 
 ## Architecture Overview
 
-### Database Schema
+### Application-Owned Example Schema
 
 ```
 documents
@@ -103,7 +107,7 @@ chunk_embeddings
 
 ### Vector Indexes
 
-The setup automatically creates HNSW indexes for optimal performance:
+The optional Docker demo creates HNSW indexes for the application-owned tables:
 
 - **Cosine Distance**: `embedding <=> query_vector`
 - **L2 Distance**: `embedding <-> query_vector`

data/docker-compose.api.yml

@@ -0,0 +1,21 @@
+services:
+  prescient-api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: prescient:local
+    ports:
+      - "9292:9292"
+    environment:
+      PRESCIENT_API_TOKEN: ${PRESCIENT_API_TOKEN:?set PRESCIENT_API_TOKEN}
+      OLLAMA_URL: ${OLLAMA_URL:-http://host.docker.internal:11434}
+    read_only: true
+    tmpfs:
+      - /tmp
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "--fail", "--silent", "http://127.0.0.1:9292/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s

data/examples/README.md

@@ -15,7 +15,25 @@ bundle install
 - `custom_prompts.rb` — system prompts and no-context/with-context templates.
 - `custom_contexts.rb` — explicit context types, field matching, formatting,
   and embedding field selection.
-- `vector_search.rb` — PostgreSQL/pgvector storage and similarity search.
+- `vector_search.rb` — `Prescient::Pgvector::Store` PostgreSQL/pgvector storage
+  and similarity search.
+- `rest_api.ru` — a tiny Rack-compatible application that mounts
+  `Prescient::API` and lists its endpoints at `/`.
+
+Run the REST API example with a Rack server such as `rackup`:
+
+```bash
+BUNDLE_WITH=rack_example bundle install
+PRESCIENT_API_TOKEN=change-me BUNDLE_WITH=rack_example \
+  bundle exec rackup -s puma examples/rest_api.ru
+curl http://localhost:9292/
+```
+
+Running `bundle exec ruby examples/rest_api.ru` directly prints the same
+endpoint catalog without starting a server.
+
+The example does not add Rack as a Prescient runtime dependency; it only uses
+the Rack-compatible `call` interface provided by `Prescient::API`.
 
 The first three examples use Ollama by default. Start Ollama and pull the
 current local models before running them:

data/examples/basic_usage.rb

@@ -67,7 +67,7 @@ end
 # Example 3: Provider comparison (if multiple providers configured)
 puts "\n=== Example 3: Provider Health Check ==="
 
-providers = [:ollama, :anthropic, :openai, :huggingface]
+providers = %i[ollama anthropic openai huggingface gemini mistral deepseek xai]
 
 providers.each do |provider_name|
   begin

data/examples/custom_contexts.rb

@@ -228,8 +228,8 @@ rescue Prescient::Error => e
   puts "❌ Error: #{e.message}"
 end
 
-# Example 4: Embedding Text Extraction
-puts "\n--- Example 4: Embedding Text Extraction ---"
+# Example 4: Embedding Text Selection
+puts "\n--- Example 4: Embedding Text Selection ---"
 
 begin
   # Configure a provider with context configs
@@ -251,7 +251,7 @@ begin
   client = Prescient.client(:embedding_demo)
   
   if client.available?
-    # Test embedding text extraction
+    # The configured embedding_fields select title, content, and tags.
     blog_post = {
       'type' => 'blog_post',
       'title' => 'Getting Started with AI',
@@ -262,12 +262,10 @@ begin
       'publish_date' => '2024-01-15'
     }
 
-    # The extract_embedding_text method will only use title, content, and tags
-    # This demonstrates how embedding generation can focus on specific fields
-    embedding_text = client.provider.send(:extract_embedding_text, blog_post)
-    puts "📊 Embedding Text Extracted:"
+    embedding_text = [blog_post['title'], blog_post['content'], blog_post['tags']].join(' ')
+    puts "📊 Embedding Text Selected:"
     puts "\"#{embedding_text}\""
-    puts "\n(Notice how only title, content, and tags are included - not author, category, or date)"
+    puts "\n(Only title, content, and tags are included in the embedding input)"
 
     # Generate actual embedding
     puts "\n🔢 Generating embedding..."
@@ -317,19 +315,6 @@ begin
     puts "🔧 Raw data (no context config):"
     random_data.each { |item| puts "   #{item}" }
     
-    puts "\n📄 How items are formatted without context config:"
-    random_data.each do |item|
-      formatted = client.provider.send(:format_context_item, item)
-      puts "   #{formatted}"
-    end
-    
-    puts "\n🔤 Embedding text extraction (automatic field filtering):"
-    random_data.each do |item|
-      embedding_text = client.provider.send(:extract_embedding_text, item)
-      puts "   \"#{embedding_text}\""
-      puts "   (Notice: excludes 'created_at', 'timestamp' - common metadata fields)"
-    end
-    
     response = client.generate_response("Summarize the key issues", random_data)
     puts "\n🤖 AI Response (using default formatting):"
     puts response[:response]

data/examples/rest_api.ru

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../lib/prescient'
+
+api = Prescient::API.new(
+  authentication: ->(env) {
+    expected = ENV.fetch('PRESCIENT_API_TOKEN', nil)
+    expected && env['HTTP_AUTHORIZATION'] == "Bearer #{expected}"
+  },
+)
+
+endpoints = Prescient::API::ROUTES.keys.map { |method, path|
+  { method: method, path: path }
+}
+
+app = ->(env) {
+  if env['REQUEST_METHOD'] == 'GET' && env['PATH_INFO'] == '/'
+    payload = JSON.generate({ name: 'Prescient API', endpoints: endpoints })
+    [200, { 'content-type' => 'application/json', 'content-length' => payload.bytesize.to_s }, [payload]]
+  else
+    api.call(env)
+  end
+}
+
+if respond_to?(:run, true)
+  run app
+else
+  puts JSON.pretty_generate({ name: 'Prescient API', endpoints: endpoints })
+end