prescient 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53a88a152c9fb689789c06dc11612905e30d76e997dbdcc1ca9906870bb01899
-  data.tar.gz: 4dba29dd0ad5ae0edbccd0f9d50d8e1eeb8815ba1aeadda838b327ec124111d6
+  metadata.gz: 176552789656cbda6e78951ab04eb0ecdfa9ffa53dcf88159bec5cdbf403cdef
+  data.tar.gz: 5173a6bdd607dc6aca121079ee6e81243a550575f4702c57133f637a31aac798
 SHA512:
-  metadata.gz: 0beee5d0fc6ca63e1d2f881055402a18ab374d8ec71f17c6e706bba7a0ec8f565bbd77ff4f1b337f100597d357a07ffcc45b37e080429199603ce3147e292579
-  data.tar.gz: 2d8214bfb8d5f61536e5c79462d560cd4d6f83215dae54cffed821fe0f23d2959adbe02ec94f522d69bd2e04adb37b52087ba364752a98e093e6605ce204abfb
+  metadata.gz: fb309c19aa67f200e806b227f392ff5181e5ef7bc1ea00a6f9a0d4cf5ebbce989c0d9b472885a1c2795efaa7789a8ed61f912453fd20594fba029f8c7bc126d4
+  data.tar.gz: 70187123148e3c0aad70f88fa469c91e3c55200c1c36b9452697109e2746cfe0fe70ef8358b766b3f99b967884aba4b846f3a8cb634c76fe9803ad45925d0e50

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.7.0] - 2025-08-17
+
+### Added
+
+- Added an explicit external-tool contract with a configurable SearXNG web-search adapter.
+- Added YAML/schema configuration for tool registration, environment references, bounded requests, and normalized search results.
+- Added `prescient search` and an annotated `web_search` configuration example.
+- Added an optional development SearXNG service to `docker-compose.yml` for runnable web-search examples.
+- Added opt-in search-to-provider context assembly through `Prescient.search_and_generate` and `prescient search --generate`.
+- Added `POST /v1/search/generate` for REST API consumers to opt in to search-result context.
+- Added `POST /v1/search` for normalized raw external-tool results without AI generation.
+- Added SearchApi as a hosted web-search adapter with engine, location, language,
+  country, API-key, timeout, and result-limit configuration.
+- Added capability groups for ordered tool-adapter fallback on transient
+  connection and rate-limit failures.
+- Documented SearXNG and SearchApi setup and CLI usage side by side.
+- Added explicit `--generate` opt-in behavior to the web-search example.
+- Added `SEARXNG_URL` environment defaults for automatic `web_search` registration.
+- Expanded `prescient config example` with documented SearXNG settings,
+  environment references, custom tool names, and direct-versus-generated usage.
+- Organized CLI help into global and search-specific option sections.
+
+## [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

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.5.0'
+gem 'prescient', '~> 0.7.0'
 ```
 
 ### 2. Replace Existing AI Service
@@ -111,6 +109,40 @@ 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
@@ -128,7 +160,68 @@ 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. Update Environment Variables
+### 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/search` | Normalized external-tool search |
+| `POST` | `/v1/search/generate` | Search with opt-in AI 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"}'
+
+curl -X POST http://localhost:3000/prescient/v1/search/generate \
+  -H "Authorization: Bearer ${PRESCIENT_API_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"Ruby HTTP clients","provider":"openai","limit":5}'
+
+curl -X POST http://localhost:3000/prescient/v1/search \
+  -H "Authorization: Bearer ${PRESCIENT_API_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"Ruby HTTP clients","limit":5}'
+```
+
+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
@@ -151,9 +244,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:**
 
@@ -199,7 +310,7 @@ class Api::V1::AiQueriesController < ApplicationController
 end
 ```
 
-### 6. Health Check Integration
+### 7. Health Check Integration
 
 ```ruby
 # app/controllers/api/v1/system/health_controller.rb
@@ -232,7 +343,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,
@@ -252,7 +363,7 @@ class Api::V1::System::HealthController < ApplicationController
 end
 ```
 
-### 7. Migration Strategy
+### 8. Migration Strategy
 
 1. **Phase 1: Side-by-side deployment**
 
@@ -271,7 +382,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
@@ -296,7 +407,7 @@ class AIServiceTest < ActiveSupport::TestCase
 end
 ```
 
-### 9. Monitoring and Logging
+### 10. Monitoring and Logging
 
 ```ruby
 # config/initializers/prescient_monitoring.rb
@@ -320,7 +431,7 @@ end
 PrescientMonitoring.setup! if Rails.env.production?
 ```
 
-### 10. Performance Optimization
+### 11. Performance Optimization
 
 ```ruby
 # app/services/ai_service.rb (enhanced)

data/README.md

@@ -2,11 +2,12 @@
 
 [![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/)
+[![Docker](https://img.shields.io/badge/Docker-GHCR-2496ED?logo=docker&logoColor=white)](https://github.com/kanutocd/prescient/pkgs/container/prescient)
 [![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.
+Prescient is a boring AI provider gateway implemented in Ruby. Configure your AI providers once, then use them through a consistent Ruby API, CLI, or REST API. Prescient handles provider selection, retries, health checks, and fallback across configured providers, including OpenAI, Anthropic, Ollama, Hugging Face, Google Gemini, Mistral, DeepSeek, and xAI.
 
 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,13 +15,15 @@ For focused guidance, see the **[examples guide](https://github.com/kanutocd/pre
 
 ## Features
 
-- **Unified Interface**: Single API for multiple AI providers
-- **Local and Cloud Support**: Ollama for local/private deployments, cloud APIs for scale
-- **Embedding Generation**: Vector embeddings for semantic search and AI applications
-- **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**: YAML, environment variable, and programmatic configuration
+- **Provider abstraction** — One consistent interface across supported AI providers
+- **Multiple interfaces** — Ruby API, CLI, and Rack-compatible REST API
+- **Text and embeddings** — Generate responses and embeddings with provider/model selection
+- **Reliability controls** — Retries, health checks, and fallback across configured providers
+- **Declarative configuration** — Versioned YAML, environment references, and JSON Schema validation
+- **Prompt and context customization** — Configurable prompt templates and context formatting
+- **External tools** — Explicit, normalized web-search integration with SearXNG and SearchApi
+- **Local and cloud support** — Ollama alongside hosted providers
+- **Optional integrations** — Docker deployment and pgvector support without making either mandatory
 
 ## Supported Providers
 
@@ -223,6 +226,64 @@ 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/search`**
+- **`POST /v1/search/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
@@ -291,25 +352,139 @@ 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:
+### External Tools
+
+External tools are opt-in capability adapters, separate from AI providers.
+Supported web-search adapters are [SearXNG](https://searxng.org/) and
+[SearchApi](https://www.searchapi.io/):
+
+#### SearXNG
+
+Setting `SEARXNG_URL` registers the default `web_search` tool for CLI and Ruby
+environment-based configuration. YAML or programmatic configuration can be
+used when more control is needed.
 
 ```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}"
+tools:
+  web_search:
+    type: searxng
+    url_env: SEARXNG_URL
+    language: en
+    categories: [general, news]
+    timeout: 5
+    max_results: 5
 ```
 
+Run the SearXNG-backed tool:
+
 ```bash
-prescient generate --prompt-templates-file prompts.yml "Summarize this"
+docker compose up -d searxng
+SEARXNG_URL=http://localhost:8080 bundle exec prescient search \
+  --format json "Ruby HTTP clients"
+```
+
+#### SearchApi
+
+[SearchApi](https://www.searchapi.io/) uses a hosted Google search engine and
+requires an API key:
+
+```yaml
+tools:
+  web_search:
+    type: searchapi
+    api_key_env: SEARCHAPI_API_KEY
+    engine: google
+    location: New York
+    hl: en
+    gl: us
+    timeout: 10
+    max_results: 5
+```
+
+The `engine` value can select another SearchApi web or product engine when its
+response uses `organic_results`, such as `bing`, `yahoo`, `yandex`,
+`amazon_search`, or `walmart_search`.
+
+Adapters can be grouped under one logical capability for ordered fallback:
+
+```yaml
+tools:
+  web_search:
+    adapters:
+      - type: searxng
+        url_env: SEARXNG_URL
+      - type: searchapi
+        api_key_env: SEARCHAPI_API_KEY
+        engine: google
+```
+
+Adapters are tried in order. Fallback is limited to transient connection and
+rate-limit failures; invalid configuration, authentication failures, and
+malformed responses are not retried with another adapter.
+
+Run the SearchApi-backed tool:
+
+```bash
+SEARCHAPI_API_KEY=your-key bundle exec prescient search \
+  --config prescient.yml --format json "Ruby HTTP clients"
+```
+
+Invoke a configured tool explicitly from Ruby or the CLI:
+
+```ruby
+result = Prescient.tool(:web_search).search('Ruby HTTP clients', limit: 3)
+```
+
+```bash
+bundle exec prescient search --config prescient.yml \
+  --tool web_search --format json "Ruby HTTP clients"
+```
+
+Results use a normalized envelope containing `tool`, `query`, `source`, and
+`results` entries with `title`, `url`, `snippet`, and `source`. Requests have
+bounded query length, timeout, result count, and response size. Tool execution
+is explicit; Prescient does not autonomously invoke tools, and tool endpoints
+are not exposed as raw tool endpoints through `Prescient::API`; the API exposes
+the explicit combined search-and-generation operation below. Other adapters can
+implement the same contract without changing provider integrations.
+
+Search results are not sent to an AI provider by default. Opt in when you want
+the normalized results assembled as generation context:
+
+```ruby
+response = Prescient.search_and_generate(
+  'Ruby HTTP clients',
+  tool: :web_search,
+  provider: :openai,
+)
 ```
 
+The CLI exposes the same opt-in behavior with `--generate`:
+
+```bash
+prescient search --generate --provider openai "Ruby HTTP clients"
+```
+
+The REST API exposes the same opt-in behavior:
+
+Raw normalized search results are available without generation:
+
+```bash
+curl -X POST http://localhost:9292/v1/search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"Ruby HTTP clients","limit":5}'
+```
+
+```bash
+curl -X POST http://localhost:9292/v1/search/generate \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"Ruby HTTP clients","provider":"openai","limit":5}'
+```
+
+Use `fallback: false` to disable provider fallback for the request. The
+response is the normalized AI provider response; omit this endpoint and use
+`POST /v1/generate` when search context is not wanted.
+
 ### Programmatic Configuration
 
 ```ruby
@@ -546,6 +721,24 @@ client = Prescient.client(:customer_service)
 response = client.generate_response("What's your return policy?")
 ```
 
+Templates can also be configured in YAML or overridden for one 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"
+```
+
 ### Template Placeholders
 
 - `%{system_prompt}` - The system/role instruction
@@ -978,6 +1171,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:
@@ -1052,6 +1269,8 @@ The included `docker-compose.yml` provides:
 
 - **ollama**: Ollama AI service with persistent model storage
 - **ollama-init**: Automatically pulls required models on startup
+- **searxng**: Optional SearXNG web-search service with JSON output enabled
+- **postgres**: Optional PostgreSQL database with pgvector support
 - **redis**: Optional caching layer for embeddings
 - **prescient-app**: Example Ruby application container
 
@@ -1210,10 +1429,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/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