prescient 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53a88a152c9fb689789c06dc11612905e30d76e997dbdcc1ca9906870bb01899
-  data.tar.gz: 4dba29dd0ad5ae0edbccd0f9d50d8e1eeb8815ba1aeadda838b327ec124111d6
+  metadata.gz: 167f50351b78b35d1ae63d3487285db48c07799ad015b5d49f46dd3c451afa49
+  data.tar.gz: 91e1895635015120c75b0b461fea017d8ec7c4b5ebd81f1d2b0c86ba37690e1d
 SHA512:
-  metadata.gz: 0beee5d0fc6ca63e1d2f881055402a18ab374d8ec71f17c6e706bba7a0ec8f565bbd77ff4f1b337f100597d357a07ffcc45b37e080429199603ce3147e292579
-  data.tar.gz: 2d8214bfb8d5f61536e5c79462d560cd4d6f83215dae54cffed821fe0f23d2959adbe02ec94f522d69bd2e04adb37b52087ba364752a98e093e6605ce204abfb
+  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,26 @@
 
 ## 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

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.6.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,56 @@ 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/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
@@ -151,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:**
 
@@ -199,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
@@ -232,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,
@@ -252,7 +351,7 @@ class Api::V1::System::HealthController < ApplicationController
 end
 ```
 
-### 7. Migration Strategy
+### 8. Migration Strategy
 
 1. **Phase 1: Side-by-side deployment**
 
@@ -271,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
@@ -296,7 +395,7 @@ class AIServiceTest < ActiveSupport::TestCase
 end
 ```
 
-### 9. Monitoring and Logging
+### 10. Monitoring and Logging
 
 ```ruby
 # config/initializers/prescient_monitoring.rb
@@ -320,7 +419,7 @@ end
 PrescientMonitoring.setup! if Rails.env.production?
 ```
 
-### 10. Performance Optimization
+### 11. Performance Optimization
 
 ```ruby
 # app/services/ai_service.rb (enhanced)

data/README.md

@@ -223,6 +223,62 @@ 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
@@ -978,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:
@@ -1210,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/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

@@ -17,6 +17,23 @@ bundle install
   and embedding field selection.
 - `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/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

data/lib/prescient/api.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'stringio'
+require 'uri'
+require_relative '../prescient'
+
+# Dependency-free Rack-compatible HTTP application for Prescient operations.
+#
+# The application exposes only generic Prescient operations. It does not
+# expose provider-specific methods, credentials, or raw provider responses.
+class Prescient::API
+  # @return [Integer] Default maximum request body size in bytes
+  DEFAULT_MAX_BODY_BYTES = 1_048_576
+  # @return [Integer] Maximum number of inputs accepted by batch embeddings
+  MAX_BATCH_SIZE = 32
+  # @return [String] HTTP API version
+  API_VERSION = '1'
+  # @return [Hash<Array<String>, Symbol>] Generic HTTP route handlers
+  ROUTES = {
+    ['GET',  '/healthz']             => :healthz_response,
+    ['GET',  '/readyz']              => :readiness_response,
+    ['GET',  '/v1/version']          => :version_response,
+    ['GET',  '/v1/providers']        => :providers_response,
+    ['GET',  '/v1/models']           => :models_response,
+    ['GET',  '/v1/capabilities']     => :capabilities_response,
+    ['GET',  '/v1/health']           => :health_response,
+    ['POST', '/v1/generate']         => :generate_response,
+    ['POST', '/v1/embeddings']       => :embeddings_response,
+    ['POST', '/v1/embeddings/batch'] => :batch_embeddings_response,
+  }.freeze
+
+  # @param authentication [#call, nil] Optional authentication hook
+  # @param max_body_bytes [Integer] Maximum accepted request body size
+  # @return [void]
+  def initialize(authentication: nil, max_body_bytes: DEFAULT_MAX_BODY_BYTES)
+    @authentication = authentication
+    @max_body_bytes = validate_body_limit(max_body_bytes)
+  end
+
+  # Handle a Rack-style environment and return a Rack response tuple.
+  # @param env [Hash] Rack-compatible request environment
+  # @return [Array(Integer, Hash, Array<String>)] HTTP status, headers, body
+  def call(env)
+    request_id = request_id_for(env)
+    public_path = request_target(env).first
+    return dispatch(env, request_id) if ['/healthz', '/readyz'].include?(public_path)
+
+    unless authenticated?(env)
+      return response(401,
+                      error_payload('authentication_required', 'authentication required',
+                                    request_id))
+    end
+
+    dispatch(env, request_id)
+  rescue StandardError => e
+    handle_exception(e, request_id)
+  end
+
+  private
+
+  def dispatch(env, request_id)
+    method = env.fetch('REQUEST_METHOD', 'GET').upcase
+    path, query = request_target(env)
+    handler = ROUTES[[method, path]]
+    return response(404, error_payload('not_found', 'route not found', request_id)) unless handler
+
+    send(handler, env, query, request_id)
+  end
+
+  def healthz_response(_env, _query, request_id)
+    json_response(200, { status: 'ok' }, request_id)
+  end
+
+  def version_response(_env, _query, request_id)
+    json_response(200, { version: Prescient::VERSION, api_version: API_VERSION }, request_id)
+  end
+
+  def generate_response(env, _query, request_id)
+    payload = request_payload(env)
+    prompt = required_string(payload, 'prompt')
+    context = payload.fetch('context', [])
+    raise ArgumentError, 'context must be an array' unless context.is_a?(Array)
+
+    client = client_for(payload)
+    result = client.generate_response(prompt, context, **generation_options(payload))
+    json_response(200, result, request_id)
+  end
+
+  def embeddings_response(env, _query, request_id)
+    payload = request_payload(env)
+    input = required_string(payload, 'input')
+    client = client_for(payload)
+    result = client.generate_embedding(input, **model_options(payload))
+    json_response(200, embedding_payload(result, client), request_id)
+  end
+
+  def batch_embeddings_response(env, _query, request_id)
+    payload = request_payload(env)
+    inputs = payload['inputs']
+    raise ArgumentError, 'inputs must be a non-empty array' unless inputs.is_a?(Array) && inputs.any?
+    raise ArgumentError, "inputs cannot contain more than #{MAX_BATCH_SIZE} items" if inputs.length > MAX_BATCH_SIZE
+    raise ArgumentError, 'inputs must contain only strings' unless inputs.all?(String)
+
+    client = client_for(payload)
+    embeddings = inputs.map { |input| client.generate_embedding(input, **model_options(payload)) }
+    result = { embeddings: embeddings, dimensions: embeddings.first.length, provider: client.provider_name.to_s }
+    json_response(200,
+                  result, request_id)
+  end
+
+  def readiness_response(_env, _query, request_id)
+    providers = Prescient.configuration.providers.keys
+    ready = providers.any? { |name|
+      begin
+        Prescient.health_check(provider: name)[:ready] == true
+      rescue Prescient::Error
+        false
+      end
+    }
+    json_response(ready ? 200 : 503, { status: ready ? 'ready' : 'not_ready' }, request_id)
+  end
+
+  def providers_response(_env, _query, request_id)
+    providers = Prescient.configuration.providers.map { |name, registration|
+      { name: name.to_s, class: registration[:class].name }
+    }
+    json_response(200, { providers: providers }, request_id)
+  end
+
+  def models_response(_env, query, request_id)
+    names = query['provider'] ? [query['provider'].to_sym] : Prescient.configuration.providers.keys
+    models = names.flat_map { |name|
+      provider = Prescient.configuration.provider(name)
+      raise Prescient::Error, "Provider not configured: #{name}" unless provider
+
+      records = if provider.respond_to?(:list_models)
+                  provider.list_models
+                elsif provider.respond_to?(:available_models)
+                  provider.available_models
+                else
+                  []
+                end
+      records.map { |model| { provider: name.to_s, model: model } }
+    }
+    json_response(200, { models: models }, request_id)
+  end
+
+  def capabilities_response(_env, _query, request_id)
+    capabilities = Prescient.configuration.providers.map { |name, registration|
+      provider = registration[:class]
+      {
+        provider:      name.to_s,
+        generation:    provider.method_defined?(:generate_response),
+        embeddings:    provider.method_defined?(:generate_embedding),
+        health:        provider.method_defined?(:health_check),
+        model_listing: provider.method_defined?(:list_models) || provider.method_defined?(:available_models),
+      }
+    }
+    json_response(200, { capabilities: capabilities }, request_id)
+  end
+
+  def health_response(_env, query, request_id)
+    if query['provider']
+      json_response(200, Prescient.health_check(provider: query['provider'].to_sym), request_id)
+    else
+      results = Prescient.configuration.providers.keys.to_h { |name|
+        [name.to_s, Prescient.health_check(provider: name)]
+      }
+      json_response(200, results, request_id)
+    end
+  end
+
+  def client_for(payload)
+    provider = payload['provider']&.to_sym
+    fallback = payload.key?('fallback') ? payload['fallback'] : true
+    raise ArgumentError, 'fallback must be boolean' unless [true, false].include?(fallback)
+
+    Prescient.client(provider, enable_fallback: fallback)
+  end
+
+  def generation_options(payload)
+    options = model_options(payload)
+    ['temperature', 'max_tokens', 'top_p'].each do |key|
+      options[key.to_sym] = payload[key] if payload.key?(key)
+    end
+    options
+  end
+
+  def model_options(payload)
+    payload['model'] ? { model: payload['model'] } : {}
+  end
+
+  def embedding_payload(embedding, client)
+    { embedding: embedding, dimensions: embedding.length, provider: client.provider_name.to_s }
+  end
+
+  def request_payload(env)
+    content_length = env['CONTENT_LENGTH'].to_i
+    raise ArgumentError, 'request body exceeds configured limit' if content_length > @max_body_bytes
+
+    body = env.fetch('rack.input', StringIO.new).read(@max_body_bytes + 1)
+    raise ArgumentError, 'request body exceeds configured limit' if body.bytesize > @max_body_bytes
+
+    parsed = JSON.parse(body)
+    raise ArgumentError, 'request body must contain a JSON object' unless parsed.is_a?(Hash)
+
+    parsed
+  end
+
+  def required_string(payload, key)
+    value = payload[key]
+    raise ArgumentError, "#{key} must be a non-empty string" unless value.is_a?(String) && !value.empty?
+
+    value
+  end
+
+  def request_target(env)
+    target = env['REQUEST_URI'] || env['PATH_INFO'] || '/'
+    path, query = target.split('?', 2)
+    [path, URI.decode_www_form(query.to_s).to_h]
+  end
+
+  def authenticated?(env)
+    return true unless @authentication
+
+    @authentication.call(env) == true
+  end
+
+  def request_id_for(env)
+    supplied = env['HTTP_X_REQUEST_ID'].to_s
+    supplied.match?(/\A[a-zA-Z0-9._:-]{1,128}\z/) ? supplied : SecureRandom.uuid
+  end
+
+  def json_response(status, payload, request_id)
+    response(status, payload.merge(request_id: request_id))
+  end
+
+  def response(status, payload)
+    body = JSON.generate(payload)
+    headers = {
+      'content-type'   => 'application/json',
+      'content-length' => body.bytesize.to_s,
+    }
+    headers['x-request-id'] = payload[:request_id] if payload[:request_id]
+    [status, headers, [body]]
+  end
+
+  def error_payload(type, message, request_id)
+    { error: { type: type, message: message }, request_id: request_id }
+  end
+
+  def error_type(error)
+    error.class.name.split('::').last.delete_suffix('Error').downcase
+  end
+
+  def error_status(error)
+    return 401 if error.is_a?(Prescient::AuthenticationError)
+    return 429 if error.is_a?(Prescient::RateLimitError)
+    return 503 if error.is_a?(Prescient::ConnectionError) || error.is_a?(Prescient::ProviderError)
+    return 422 if error.is_a?(Prescient::ModelNotAvailableError)
+
+    500
+  end
+
+  def handle_exception(error, request_id)
+    case error
+    when JSON::ParserError
+      response(400, error_payload('invalid_json', 'request body must contain valid JSON', request_id))
+    when ArgumentError
+      response(400, error_payload('invalid_request', error.message, request_id))
+    when Prescient::Error
+      response(error_status(error), error_payload(error_type(error), error.message, request_id))
+    else
+      response(500, error_payload('internal_error', 'internal server error', request_id))
+    end
+  end
+
+  def validate_body_limit(value)
+    return value if value.is_a?(Integer) && value.positive?
+
+    raise ArgumentError, 'max_body_bytes must be a positive integer'
+  end
+end

data/lib/prescient/cli.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'optparse'
 require 'yaml'
+require_relative '../prescient'
 
 # Command-line interface for common Prescient operations.
 class Prescient::CLI

data/lib/prescient/version.rb

@@ -2,5 +2,5 @@
 
 module Prescient
   # Current Prescient gem version.
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/prescient.rb

@@ -14,7 +14,6 @@ require_relative 'prescient/provider/deepseek'
 require_relative 'prescient/provider/xai'
 require_relative 'prescient/configuration_loader'
 require_relative 'prescient/client'
-require_relative 'prescient/cli'
 
 # Main Prescient module for AI provider abstraction
 #
@@ -35,6 +34,9 @@ require_relative 'prescient/cli'
 #   embedding = client.generate_embedding("Some text to embed")
 #   puts embedding.length # => 1536 (for OpenAI text-embedding-3-small)
 module Prescient
+  autoload :API, 'prescient/api'
+  autoload :CLI, 'prescient/cli'
+
   # Configure Prescient with custom settings and providers
   #
   # @example Configure with custom provider

data/sig/prescient.rbs

@@ -298,6 +298,16 @@ module Prescient
     def run: () -> Integer
   end
 
+  class API
+    DEFAULT_MAX_BODY_BYTES: Integer
+    MAX_BATCH_SIZE: Integer
+    API_VERSION: String
+    ROUTES: Hash[Array[String], Symbol]
+
+    def initialize: (?authentication: untyped, ?max_body_bytes: Integer) -> void
+    def call: (Hash[String, untyped]) -> [Integer, Hash[String, String], Array[String]]
+  end
+
   class ConfigurationLoader
     CONFIGURATION_VERSION: Integer
     TOP_LEVEL_KEYS: Array[String]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prescient
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -33,11 +33,13 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".dockerignore"
 - ".env.example"
 - ".rubocop.yml"
 - ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- Dockerfile
 - Dockerfile.example
 - INTEGRATION_GUIDE.md
 - LICENSE.txt
@@ -50,14 +52,17 @@ files:
 - db/init/03_create_indexes.sql
 - db/init/04_insert_sample_data.sql
 - db/migrate/001_create_prescient_tables.rb
+- docker-compose.api.yml
 - docker-compose.yml
 - examples/README.md
 - examples/basic_usage.rb
 - examples/custom_contexts.rb
 - examples/custom_prompts.rb
+- examples/rest_api.ru
 - examples/vector_search.rb
 - exe/prescient
 - lib/prescient.rb
+- lib/prescient/api.rb
 - lib/prescient/base.rb
 - lib/prescient/cli.rb
 - lib/prescient/client.rb