prescient 0.7.0 → 0.8.0

data/lib/prescient/document_source.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Prescient
+  # Bounded sources of JSON documents suitable for generation context.
+  module DocumentSource
+    # @return [Integer] Default maximum number of documents
+    DEFAULT_MAX_DOCUMENTS = 100
+    # @return [Integer] Default maximum serialized source size
+    DEFAULT_MAX_BYTES = 1_048_576
+
+    # Common validation and size-bound behavior for document sources.
+    class Base
+      def initialize(max_documents: DEFAULT_MAX_DOCUMENTS, max_bytes: DEFAULT_MAX_BYTES)
+        @max_documents = positive_integer(max_documents, "max_documents")
+        @max_bytes = positive_integer(max_bytes, "max_bytes")
+      end
+
+      # @return [Array<Hash>] JSON object documents
+      def fetch
+        raise NotImplementedError
+      end
+
+      private
+
+      def normalize(value)
+        documents = value.is_a?(Array) ? value : [value]
+        raise Prescient::Error, "document source must contain JSON objects" unless documents.all?(Hash)
+        if documents.length > @max_documents
+          raise Prescient::Error, "document source cannot contain more than #{@max_documents} documents"
+        end
+
+        serialized = JSON.generate(documents)
+        raise Prescient::Error, "document source exceeds #{@max_bytes} bytes" if serialized.bytesize > @max_bytes
+
+        documents
+      end
+
+      def parse_json(value)
+        normalize(JSON.parse(value))
+      rescue JSON::ParserError => e
+        raise Prescient::Error, "document source contains invalid JSON: #{e.message}"
+      end
+
+      def positive_integer(value, name)
+        return value if value.is_a?(Integer) && value.positive?
+
+        raise Prescient::Error, "#{name} must be a positive integer"
+      end
+    end
+
+    # Validate and bound application-provided JSON documents.
+    class Memory < Base
+      # @param documents [Array<Hash>, Hash] Documents to validate
+      def initialize(documents:, **options)
+        super(**options)
+        @documents = documents
+      end
+
+      # @return [Array<Hash>] Validated documents
+      def fetch
+        normalize(@documents)
+      end
+    end
+
+    # Read JSON documents from a local file.
+    class JsonFile < Base
+      # @param path [String] JSON file path
+      def initialize(path:, **options)
+        super(**options)
+        @path = path
+        return if @path.is_a?(String) && !@path.empty?
+
+        raise Prescient::Error, "document source path must be a non-empty string"
+      end
+
+      # @return [Array<Hash>] Documents loaded from the file
+      def fetch
+        raise Prescient::Error, "document source file not found: #{@path}" unless File.file?(@path)
+        raise Prescient::Error, "document source file exceeds #{@max_bytes} bytes" if File.size(@path) > @max_bytes
+
+        parse_json(File.read(@path))
+      rescue Errno::EACCES => e
+        raise Prescient::Error, "unable to read document source: #{e.message}"
+      end
+    end
+
+    # Read JSON documents from a Redis-compatible client.
+    # The client is injected to keep Redis optional for gem consumers.
+    class RedisJson < Base
+      # @param client [#get] Redis-compatible client
+      # @param key [String] Redis key containing a JSON document or array
+      def initialize(client:, key:, **options)
+        super(**options)
+        @client = client
+        @key = key
+        return if @key.is_a?(String) && !@key.empty?
+
+        raise Prescient::Error, "Redis document key must be a non-empty string"
+      end
+
+      # @return [Array<Hash>] Documents loaded from Redis
+      def fetch
+        value = @client.get(@key)
+        raise Prescient::Error, "Redis document source key not found: #{@key}" unless value
+
+        parse_json(value)
+      rescue NoMethodError
+        raise Prescient::Error, "Redis document source client must provide get"
+      end
+    end
+  end
+end

data/lib/prescient/errors.rb

@@ -3,9 +3,7 @@
 module Prescient
   # Base error class for all Prescient-specific errors
   class Error < StandardError
-    attr_reader :provider
-    attr_reader :operation
-    attr_reader :status
+    attr_reader :provider, :operation, :status
 
     def initialize(message = nil, provider: nil, operation: nil, status: nil)
       super(message)

data/lib/prescient/mcp/authentication.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::MCP
+  # Standard bearer-token authentication policy for HTTP MCP transports.
+  module Authentication
+    # Authenticates requests with a configured bearer token.
+    class BearerToken
+      def initialize(token:, principal: nil)
+        raise ArgumentError, "token must be a non-empty string" unless token.is_a?(String) && !token.empty?
+
+        @token = token
+        @principal = principal
+      end
+
+      # Authenticate a Rack environment without exposing the token.
+      # @param env [Hash] Rack environment
+      # @return [Object, false] Principal on success or false on failure
+      def call(env)
+        value = env["HTTP_AUTHORIZATION"].to_s
+        scheme, candidate = value.split(" ", 2)
+        return false unless scheme&.casecmp("Bearer")&.zero? && secure_equal?(candidate.to_s, @token)
+
+        @principal || { type: "bearer" }
+      end
+
+      private
+
+      def secure_equal?(candidate, expected)
+        return false unless candidate.bytesize == expected.bytesize
+
+        OpenSSL.fixed_length_secure_compare(candidate, expected)
+      end
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/mcp/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren, Layout/IndentationWidth
+module Prescient::MCP
+    # Policy and capability configuration for the optional MCP adapter.
+    class Configuration
+      # @return [Integer] Maximum default MCP input size in bytes
+      DEFAULT_MAX_INPUT_BYTES = 64_000
+      # @return [Array<String>] Default MCP tools
+      DEFAULT_TOOLS = %w[
+        prescient_generate prescient_embed prescient_providers prescient_health prescient_agent
+      ].freeze
+      # @return [Array<String>] Resources supported by the adapter
+      SUPPORTED_RESOURCES = ["prescient://providers", "prescient://health"].freeze
+
+      attr_reader :name, :version, :max_input_bytes, :tools, :resources
+
+      def initialize(name: "prescient", version: Prescient::VERSION,
+                     max_input_bytes: DEFAULT_MAX_INPUT_BYTES,
+                     tools: DEFAULT_TOOLS,
+                     resources: ["prescient://providers", "prescient://health"])
+        @name = name
+        @version = version
+        @max_input_bytes = validate_limit(max_input_bytes)
+        @tools = Array(tools).map(&:to_s).freeze
+        @resources = Array(resources).map(&:to_s).freeze
+      end
+
+      private
+
+      def validate_limit(value)
+        return value if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError, "max_input_bytes must be a positive integer"
+      end
+    end
+end
+# rubocop:enable Style/ClassAndModuleChildren, Layout/IndentationWidth

data/lib/prescient/mcp/rack.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+require "securerandom"
+require "stringio"
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::MCP
+  # Optional Rack-compatible MCP HTTP handler with explicit authentication.
+  # rubocop:disable Metrics/ClassLength
+  class Rack
+    # MCP protocol version supported by the HTTP transport.
+    # @return [String] Protocol version identifier
+    PROTOCOL_VERSION = "2025-06-18"
+    # Rack environment key containing the MCP session identifier.
+    # @return [String] Rack header key
+    SESSION_HEADER = "HTTP_MCP_SESSION_ID"
+    # Rack environment key containing the MCP protocol version.
+    # @return [String] Rack header key
+    PROTOCOL_HEADER = "HTTP_MCP_PROTOCOL_VERSION"
+    # Default policy allowing requests without an Origin header restriction.
+    # @return [Array<String>] Empty Origin allowlist
+    ALLOWED_ORIGINS_DEFAULT = [].freeze
+
+    def initialize(authentication:, server: Server.new, request_context: nil,
+                   max_body_bytes: Configuration::DEFAULT_MAX_INPUT_BYTES,
+                   allowed_origins: ALLOWED_ORIGINS_DEFAULT, session_ttl: 3600)
+      @server = server
+      @authentication = authentication
+      @request_context = request_context
+      @max_body_bytes = validate_limit(max_body_bytes)
+      @allowed_origins = Array(allowed_origins).map(&:to_s).freeze
+      @session_ttl = validate_session_ttl(session_ttl)
+      @sessions = {}
+      @sessions_lock = Monitor.new
+    end
+
+    # Handle one MCP Streamable HTTP request.
+    # @param env [Hash] Rack environment
+    # @return [Array] Rack response
+    def call(env)
+      method = env.fetch("REQUEST_METHOD", "GET").upcase
+      unless %w[POST GET DELETE].include?(method)
+        return response(
+          405, { error: "method_not_allowed" }, { "allow" => "POST, GET, DELETE" }
+        )
+      end
+      return response(403, { error: "origin_not_allowed" }) unless origin_allowed?(env)
+
+      authentication = authenticate(env)
+      unless authentication
+        return response(401, { error: "authentication_required" }, { "www-authenticate" => "Bearer" })
+      end
+
+      return post(env, authentication) if method == "POST"
+      return get(env, authentication) if method == "GET"
+
+      delete(env, authentication)
+    rescue JSON::ParserError
+      response(400, { error: "invalid_json" })
+    rescue SessionNotFoundError
+      response(404, { error: "session_not_found" })
+    rescue AuthenticationError
+      response(401, { error: "authentication_failed" })
+    rescue ArgumentError
+      response(400, { error: "invalid_request" })
+    rescue StandardError
+      response(500, { error: "internal_error" })
+    end
+
+    private
+
+    def post(env, authentication)
+      request = parse_request(env)
+      initialize_request = request["method"] == "initialize"
+      session_id = env[SESSION_HEADER]
+      if initialize_request
+        raise ArgumentError, "initialize must not include a session" if session_id
+
+        validate_protocol!(request)
+        result = @server.dispatch(request, context: request_context(env, authentication))
+        session_id = new_session(authentication)
+        return response_for(request, result, 200, headers: { "mcp-session-id" => session_id })
+      end
+
+      session = session_for(session_id)
+      validate_session!(session, authentication)
+      validate_protocol_header!(env)
+      result = @server.dispatch(request, context: request_context(env, authentication))
+      return response(202, nil) if notification?(request)
+
+      response_for(request, result, 200, sse: accepts_sse?(env))
+    end
+
+    def parse_request(env)
+      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
+
+      request = JSON.parse(body)
+      raise ArgumentError, "request must be an object" unless request.is_a?(Hash)
+      raise ArgumentError, "request must be JSON-RPC 2.0" unless request["jsonrpc"] == "2.0"
+      raise ArgumentError, "request method must be a string" unless request["method"].is_a?(String)
+
+      request
+    end
+
+    def get(env, authentication)
+      session = session_for(env[SESSION_HEADER])
+      validate_session!(session, authentication)
+      validate_protocol_header!(env)
+      raise ArgumentError, "GET requires text/event-stream" unless accepts_sse?(env)
+
+      response(200, nil, { "content-type" => "text/event-stream", "cache-control" => "no-cache",
+                           "x-accel-buffering" => "no" }, body: ": keep-alive\n\n")
+    end
+
+    def delete(env, authentication)
+      session_id = env[SESSION_HEADER]
+      session = session_for(session_id)
+      validate_session!(session, authentication)
+      validate_protocol_header!(env)
+      @sessions_lock.synchronize { @sessions.delete(session_id) }
+      [204, {}, []]
+    end
+
+    def authenticate(env)
+      result = @authentication.call(env)
+      result == false || result.nil? ? nil : result
+    end
+
+    def origin_allowed?(env)
+      origin = env["HTTP_ORIGIN"]
+      origin.nil? || @allowed_origins.include?(origin)
+    end
+
+    def new_session(authentication)
+      session_id = SecureRandom.uuid
+      expires_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @session_ttl
+      @sessions_lock.synchronize do
+        prune_expired_sessions
+        @sessions[session_id] = { authentication: authentication, expires_at: expires_at }
+      end
+      session_id
+    end
+
+    def session_for(session_id)
+      raise ArgumentError, "MCP session is required" if session_id.to_s.empty?
+
+      session = @sessions_lock.synchronize do
+        prune_expired_sessions
+        @sessions[session_id]
+      end
+      raise SessionNotFoundError unless session
+
+      session
+    end
+
+    def validate_session!(session, authentication)
+      return if session[:authentication] == authentication
+
+      raise AuthenticationError
+    end
+
+    def validate_protocol!(request)
+      version = request.dig("params", "protocolVersion")
+      return if version.nil? || version == PROTOCOL_VERSION
+
+      raise ArgumentError, "unsupported MCP protocol version"
+    end
+
+    def validate_protocol_header!(env)
+      return if env[PROTOCOL_HEADER].to_s == PROTOCOL_VERSION
+
+      raise ArgumentError, "MCP protocol version header is required"
+    end
+
+    def notification?(request)
+      !request.key?("id")
+    end
+
+    def accepts_sse?(env)
+      env.fetch("HTTP_ACCEPT", "").split(",").map(&:strip).include?("text/event-stream")
+    end
+
+    def response_for(request, result, status, sse: false, headers: {})
+      payload = { jsonrpc: "2.0", id: request["id"], result: }
+      if sse
+        body = "data: #{JSON.generate(payload)}\n\n"
+        sse_headers = headers.merge("content-type" => "text/event-stream", "cache-control" => "no-cache")
+        return response(status, nil, sse_headers, body:)
+      end
+
+      response(status, payload, headers)
+    end
+
+    def request_context(env, authentication)
+      base = {
+        request_id: SecureRandom.uuid,
+        tenant_id: env["HTTP_X_TENANT_ID"],
+        principal: authentication == true ? env["REMOTE_USER"] : authentication
+      }.compact
+      return base unless @request_context
+
+      context = @request_context.call(env)
+      raise ArgumentError, "request context hook must return a mapping" unless context.is_a?(Hash)
+
+      base.merge(context)
+    end
+
+    def response(status, payload, headers = {}, body: nil)
+      body ||= payload.nil? ? "" : JSON.generate(payload)
+      response_headers = { "content-type" => "application/json", "content-length" => body.bytesize.to_s }
+      [status, response_headers.merge(headers), body.empty? ? [] : [body]]
+    end
+
+    def validate_limit(value)
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "max_body_bytes must be a positive integer"
+    end
+
+    def validate_session_ttl(value)
+      return value if value.is_a?(Numeric) && value.positive?
+
+      raise ArgumentError, "session_ttl must be a positive number"
+    end
+
+    def prune_expired_sessions
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @sessions.delete_if { |_id, session| session[:expires_at] <= now }
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+
+  class SessionNotFoundError < StandardError
+  end
+
+  # Raised when an authenticated request does not own the MCP session.
+  class AuthenticationError < StandardError
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/mcp/server.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren, Layout/IndentationWidth
+module Prescient::MCP
+    # Dependency-free MCP capability adapter over Prescient's public API.
+    class Server
+      # rubocop:disable Layout/HashAlignment
+      TOOL_DEFINITIONS = {
+        "prescient_generate" => {
+          description:  "Generate a text response.",
+          input_schema: { type: "object", required: ["prompt"] }
+        },
+        "prescient_embed" => {
+          description:  "Generate an embedding.",
+          input_schema: { type: "object", required: ["input"] }
+        },
+        "prescient_providers" => {
+          description:  "List configured providers.",
+          input_schema: { type: "object" }
+        },
+        "prescient_health" => {
+          description:  "Check configured provider health.",
+          input_schema: { type: "object" }
+        },
+        "prescient_agent" => {
+          description:  "Run a bounded agent task with explicitly supplied tools.",
+          input_schema: { type: "object", required: ["prompt"] }
+        }
+      }.freeze
+      # rubocop:enable Layout/HashAlignment
+
+      def initialize(configuration: Configuration.new, client_factory: nil, authorization: nil)
+        @configuration = configuration
+        @client_factory = client_factory || ->(provider) { Prescient.client(provider) }
+        @authorization = authorization
+      end
+
+      # Return the MCP initialization response.
+      # @return [Hash] Server capabilities and metadata
+      def initialize_result
+        # rubocop:disable Layout/HashAlignment
+        {
+          protocolVersion: "2025-06-18",
+          serverInfo:   { name: @configuration.name, version: @configuration.version },
+          capabilities: { tools: {}, resources: {} }
+        }
+        # rubocop:enable Layout/HashAlignment
+      end
+
+      # Dispatch one MCP JSON-RPC method.
+      # @param request [Hash] JSON-RPC request
+      # @param context [Hash] Request-scoped context
+      # @return [Hash] Method result
+      def dispatch(request, context: {})
+        case request["method"]
+        when "initialize" then initialize_result
+        when "notifications/initialized", "notifications/cancelled", "notifications/progress" then nil
+        when "tools/list" then { tools: }
+        when "tools/call"
+          call_tool(request.dig("params", "name"), request.dig("params", "arguments") || {}, context:)
+        when "resources/list" then { resources: }
+        when "resources/read" then read_resource(request.dig("params", "uri"))
+        else raise ArgumentError, "MCP method not found: #{request["method"]}"
+        end
+      end
+
+      # Return enabled MCP tool definitions.
+      # @return [Array<Hash>] Discoverable tools
+      def tools
+        @configuration.tools.filter_map do |name|
+          definition = TOOL_DEFINITIONS[name]
+          definition && { name:, **definition }
+        end
+      end
+
+      # Return enabled MCP resources.
+      # @return [Array<Hash>] Discoverable resources
+      def resources
+        @configuration.resources.filter_map do |uri|
+          next unless Configuration::SUPPORTED_RESOURCES.include?(uri)
+
+          { uri:, name: uri.delete_prefix("prescient://"), mimeType: "application/json" }
+        end
+      end
+
+      # Execute one enabled MCP tool.
+      # @param name [String, Symbol] Tool name
+      # @param arguments [Hash] Tool arguments
+      # @param context [Hash] Request-scoped context
+      # @return [Hash] MCP tool result
+      def call_tool(name, arguments = {}, context: {})
+        ensure_enabled!(name)
+        validate_input(arguments)
+        authorize!(name, arguments, context)
+        result = case name.to_s
+                 when "prescient_generate" then generate(arguments)
+                 when "prescient_embed" then embed(arguments)
+                 when "prescient_providers" then providers
+                 when "prescient_health" then health(arguments)
+                 when "prescient_agent" then agent(arguments, context)
+                 else raise ArgumentError, "MCP tool not enabled: #{name}"
+                 end
+        { content: [{ type: "text", text: JSON.generate(result) }], isError: false }
+      rescue StandardError => e
+        { content: [{ type: "text", text: JSON.generate(error: safe_error(e)) }], isError: true }
+      end
+
+      # Read one enabled MCP resource.
+      # @param uri [String, Symbol] Resource URI
+      # @return [Hash] MCP resource response
+      def read_resource(uri)
+        payload = case uri.to_s
+                  when "prescient://providers" then providers
+                  when "prescient://health" then health({})
+                  else raise ArgumentError, "MCP resource not enabled: #{uri}"
+                  end
+        { contents: [{ uri:, mimeType: "application/json", text: JSON.generate(payload) }] }
+      end
+
+      private
+
+      def generate(arguments)
+        prompt = required_string(arguments, "prompt")
+        client_for(arguments).generate_response(prompt, arguments.fetch("context", []), **model_options(arguments))
+      end
+
+      def embed(arguments)
+        input = required_string(arguments, "input")
+        embedding = client_for(arguments).generate_embedding(input, **model_options(arguments))
+        { embedding:, dimensions: embedding.length }
+      end
+
+      def providers
+        { providers: Prescient.configuration.providers.map do |name, registration|
+          { name: name.to_s, class: registration[:class].name }
+        end }
+      end
+
+      def health(arguments)
+        provider = arguments["provider"]
+        return Prescient.health_check(provider: provider.to_sym) if provider
+
+        Prescient.configuration.providers.keys.to_h { |name| [name.to_s, Prescient.health_check(provider: name)] }
+      end
+
+      def agent(arguments, context)
+        require "prescient/agent"
+        configuration = Prescient::Agent::Configuration.new(max_loops: arguments.fetch("max_loops", 5))
+        result = Prescient::Agent::Runtime.new(
+          client: client_for(arguments),
+          tool_names: arguments.fetch("tools", []),
+          configuration: configuration,
+          authorization: @authorization,
+          request_context: context,
+          generation_options: model_options(arguments)
+        ).run(required_string(arguments, "prompt"))
+        result.to_h
+      end
+
+      def client_for(arguments)
+        @client_factory.call(arguments["provider"]&.to_sym)
+      end
+
+      def model_options(arguments)
+        arguments["model"] ? { model: arguments["model"] } : {}
+      end
+
+      def required_string(arguments, key)
+        value = arguments[key]
+        raise ArgumentError, "#{key} must be a non-empty string" unless value.is_a?(String) && !value.empty?
+
+        value
+      end
+
+      def validate_input(arguments)
+        raise ArgumentError, "MCP arguments must be an object" unless arguments.is_a?(Hash)
+        return unless JSON.generate(arguments).bytesize > @configuration.max_input_bytes
+
+        raise ArgumentError, "MCP arguments exceed configured limit"
+      end
+
+      def ensure_enabled!(name)
+        return if @configuration.tools.include?(name.to_s)
+
+        raise ArgumentError, "MCP tool not enabled: #{name}"
+      end
+
+      def authorize!(name, arguments, context)
+        return unless @authorization
+        return if @authorization.call(tool: name.to_sym, arguments: arguments.dup, context: context.dup) == true
+
+        raise Prescient::AuthenticationError, "MCP authorization denied"
+      end
+
+      def safe_error(error)
+        return { type: "invalid_request", message: error.message } if error.is_a?(ArgumentError)
+
+        { type: "internal_error", message: "MCP operation failed" }
+      end
+    end
+end
+# rubocop:enable Style/ClassAndModuleChildren, Layout/IndentationWidth

data/lib/prescient/mcp/stdio.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren, Layout/IndentationWidth
+module Prescient::MCP
+    # Minimal newline-delimited JSON-RPC transport for local MCP clients.
+    class Stdio
+      def initialize(server: Server.new, input: $stdin, output: $stdout)
+        @server = server
+        @input = input
+        @output = output
+      end
+
+      # Process newline-delimited JSON-RPC requests until input closes.
+      # @return [void]
+      def run
+        @input.each_line do |line|
+          request = JSON.parse(line)
+          @output.puts(JSON.generate(handle(request)))
+          @output.flush
+        rescue JSON::ParserError
+          @output.puts(JSON.generate(error_response(nil, -32_700, "invalid JSON")))
+        end
+      end
+
+      private
+
+      def handle(request)
+        id = request["id"]
+        result = @server.dispatch(request)
+        { jsonrpc: "2.0", id:, result: }
+      rescue ArgumentError
+        error_response(id, -32_601, "MCP method not found")
+      rescue StandardError
+        error_response(id, -32_600, "MCP operation failed")
+      end
+
+      def error_response(id, code, message)
+        { jsonrpc: "2.0", id:, error: { code:, message: } }
+      end
+    end
+end
+# rubocop:enable Style/ClassAndModuleChildren, Layout/IndentationWidth