prescient 0.5.0 → 0.7.0

data/docker-compose.yml

@@ -91,6 +91,26 @@ services:
       retries: 3
       start_period: 30s
 
+  # Optional SearXNG instance for the external web-search example.
+  searxng:
+    image: searxng/searxng:latest
+    container_name: prescient-searxng
+    ports:
+      - "8080:8080"
+    environment:
+      - SEARXNG_BASE_URL=http://localhost:8080/
+      - SEARXNG_SECRET=${SEARXNG_SECRET:-prescient-development-secret}
+    volumes:
+      - ./searxng/settings.yml:/etc/searxng/settings.yml:ro
+      - searxng_cache:/var/cache/searxng
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/')"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
   # Optional: Redis for caching embeddings (useful for development)
   redis:
     image: redis:7-alpine
@@ -145,6 +165,8 @@ volumes:
     driver: local
   redis_data:
     driver: local
+  searxng_cache:
+    driver: local
 
 networks:
   default:

data/examples/README.md

@@ -17,6 +17,38 @@ 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 `/`.
+- `web_search.rb` — explicit SearXNG tool invocation with normalized JSON output.
+
+The same `web_search` capability can use SearchApi instead of SearXNG when the
+tool is configured with `type: searchapi` and `SEARCHAPI_API_KEY`.
+
+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/
+```
+
+The endpoint catalog includes `POST /v1/search/generate`. With a configured
+SearXNG tool and AI provider, call it explicitly to feed search results into
+generation:
+
+```bash
+curl -X POST http://localhost:9292/v1/search/generate \
+  -H 'Authorization: Bearer change-me' \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"Ruby HTTP clients","provider":"openai","limit":5}'
+```
+
+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:
@@ -40,6 +72,25 @@ configuration. The scripts are demonstrations rather than isolated test
 fixtures; they may make real provider requests when the configured service is
 available.
 
+The web-search example requires a reachable SearXNG instance:
+
+```bash
+docker compose up -d searxng
+SEARXNG_URL=http://localhost:8080 bundle exec ruby examples/web_search.rb "Ruby HTTP clients"
+```
+
+The example returns normalized search results directly by default. Opt in to
+feeding those results to the configured AI provider with `--generate`:
+
+```bash
+SEARXNG_URL=http://localhost:8080 PRESCIENT_PROVIDER=openai \
+  bundle exec ruby examples/web_search.rb --generate "Ruby HTTP clients"
+```
+
+Omit `--generate` to keep the search results direct. `PRESCIENT_PROVIDER` is
+only used with `--generate` and may be omitted when the default provider is
+configured.
+
 See the [main README](../README.md) for configuration, fallback behavior,
 prompt templates, context exclusions, embeddings, and the public API. Rails
 applications can also use the [integration guide](../INTEGRATION_GUIDE.md),

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/examples/web_search.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../lib/prescient'
+
+generate = ARGV.delete('--generate')
+if ARGV.include?('--help')
+  puts 'Usage: ruby examples/web_search.rb [--generate] [QUERY]'
+  puts '  --generate  Feed normalized search results to the configured AI provider'
+  puts '  PRESCIENT_PROVIDER  Provider used with --generate (default: configured provider)'
+  exit
+end
+
+query = ARGV.empty? ? 'Ruby HTTP clients' : ARGV.join(' ')
+
+Prescient.configure do |config|
+  config.add_tool(
+    :web_search,
+    Prescient::Tool::SearXNG,
+    url: ENV.fetch('SEARXNG_URL', 'http://localhost:8080'),
+  )
+end
+
+result = if generate
+           Prescient.search_and_generate(
+             query,
+             provider: ENV['PRESCIENT_PROVIDER']&.to_sym,
+             limit:    20,
+           )
+         else
+           Prescient.tool(:web_search).search(query, limit: 20)
+         end
+
+puts JSON.pretty_generate(result)

data/lib/prescient/api.rb

@@ -0,0 +1,337 @@
+# 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/search']           => :search_response,
+    ['POST', '/v1/search/generate']  => :search_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 search_generate_response(env, _query, request_id)
+    payload = request_payload(env)
+    query = required_string(payload, 'query')
+    tool = search_tool_name(payload)
+    fallback = search_fallback(payload)
+    limit = search_limit(payload)
+
+    result = Prescient.search_and_generate(
+      query,
+      tool:            tool,
+      provider:        payload['provider']&.to_sym,
+      limit:           limit,
+      enable_fallback: fallback,
+      **generation_options(payload),
+    )
+    json_response(200, result, request_id)
+  end
+
+  def search_response(env, _query, request_id)
+    payload = request_payload(env)
+    query = required_string(payload, 'query')
+    tool_name = search_tool_name(payload)
+    tool = Prescient.tool(tool_name)
+    raise Prescient::ToolConfigurationError, "tool not configured: #{tool_name}" unless tool
+
+    result = tool.search(query, limit: search_limit(payload))
+    json_response(200, result, request_id)
+  end
+
+  def search_tool_name(payload)
+    value = payload.fetch('tool', 'web_search')
+    raise ArgumentError, 'tool must be a non-empty string' unless value.is_a?(String) && !value.empty?
+
+    value.to_sym
+  end
+
+  def search_fallback(payload)
+    fallback = payload.key?('fallback') ? payload['fallback'] : true
+    raise ArgumentError, 'fallback must be boolean' unless [true, false].include?(fallback)
+
+    fallback
+  end
+
+  def search_limit(payload)
+    limit = payload['limit']
+    raise ArgumentError, 'limit must be a positive integer' if limit && (!limit.is_a?(Integer) || !limit.positive?)
+
+    limit
+  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