parse-stack-next 5.7.3 → 5.7.5

data/lib/parse/embeddings.rb

@@ -19,7 +19,9 @@ module Parse
   # * {Cohere}    — embed-{english,multilingual}-v3.0 and `*-light-v3.0`.
   #   Distinguishes `:search_query` / `:search_document` at the wire.
   # * {Voyage}    — voyage-4 family (incl. open-weight `voyage-4-nano`),
-  #   voyage-3 family, voyage-code-3, voyage-finance-2, voyage-law-2.
+  #   voyage-3 family, voyage-code-4, voyage-code-3, voyage-finance-2,
+  #   voyage-law-2, multimodal, and contextualized chunk models
+  #   (voyage-context-4, voyage-context-3).
   #   Distinguishes input types.
   # * {Jina}      — jina-embeddings-v3/v4/v5 (text + omni-text mode),
   #   jina-code-embeddings-{0.5b,1.5b}. Matryoshka via `dimensions:`.

data/lib/parse/model/core/embed_managed.rb

@@ -428,7 +428,10 @@ module Parse
         #
         # @param field [Symbol, nil] limit to one embed target; nil
         #   processes every declared directive.
-        # @param batch_size [Integer] rows fetched per round (default 100).
+        # @param batch_size [Integer] rows fetched per query page (default
+        #   100). This pages the records; it does NOT batch provider
+        #   requests. Each record is saved individually and makes its own
+        #   embedding call.
         # @param limit [Integer, nil] stop after re-embedding at most
         #   this many records across all directives; nil = no cap.
         # @param where [Hash, nil] extra query constraints (e.g.
@@ -527,7 +530,10 @@ module Parse
         #
         # @param field [Symbol, nil] limit the backfill to one embed
         #   target; nil processes every declared directive.
-        # @param batch_size [Integer] rows fetched per round (default 100).
+        # @param batch_size [Integer] rows fetched per query page (default
+        #   100). This pages the records; it does NOT batch provider
+        #   requests. Each record is saved individually and makes its own
+        #   embedding call.
         # @param limit [Integer, nil] stop after embedding at most this
         #   many records across all directives; nil = no cap.
         # @param where [Hash, nil] extra query constraints AND-ed with the

data/lib/parse/mongodb.rb

@@ -69,6 +69,9 @@ module Parse
   #
   # @note Requires the 'mongo' gem to be installed. Add to your Gemfile:
   #   gem 'mongo', '~> 2.18'
+  #   Use 2.26 or newer against MongoDB 9.0, which is the first driver
+  #   release that handles 9.0's overload (Intelligent Workload
+  #   Management) errors.
   module MongoDB
     # Error raised when mongo gem is not available
     class GemNotAvailable < StandardError; end
@@ -191,6 +194,17 @@ module Parse
       find listDatabases connPoolStats serverStatus
     ].freeze
 
+    # MongoDB error code for QueryPlanKilled. MongoDB 9.0 kills a running
+    # query with it when an indexed field the query references becomes
+    # multikey (an insert or update stores an array there) mid-flight.
+    MONGO_QUERY_PLAN_KILLED_CODE = 175
+
+    # How many times a read killed by {MONGO_QUERY_PLAN_KILLED_CODE} is
+    # re-run before the error propagates. MongoDB's guidance is to re-run
+    # once the write that changed the index completes, so a small budget
+    # is enough; a persistent kill is a real failure the caller sees.
+    QUERY_KILLED_RETRIES = 2
+
     class << self
       # @!attribute [rw] enabled
       #   Feature flag to enable/disable direct MongoDB queries.
@@ -1862,7 +1876,7 @@ module Parse
           if (mode = normalize_read_preference(read_preference))
             coll = coll.with(read: { mode: mode })
           end
-          results = coll.aggregate(pipeline, agg_opts).to_a
+          results = with_query_killed_retry(collection_name) { coll.aggregate(pipeline, agg_opts).to_a }
           Parse::ACLScope.redact_results!(results, resolution)
 
           # Post-fetch pointerFields filter: drop rows where none of the
@@ -2145,7 +2159,7 @@ module Parse
           cursor = cursor.projection(options[:projection]) if options[:projection]
           cursor = cursor.hint(options[:hint]) unless options[:hint].nil?
           cursor = cursor.max_time_ms(max_time_ms) if max_time_ms
-          results = cursor.to_a
+          results = with_query_killed_retry(collection_name) { cursor.to_a }
 
           if applied_default_limit && results.size > DEFAULT_FIND_LIMIT
             # Trim the sentinel row and warn — the caller asked for everything
@@ -2451,6 +2465,39 @@ module Parse
       # MongoDB error code for MaxTimeMSExpired
       MONGO_MAX_TIME_MS_EXPIRED_CODE = 50
 
+      # Run a read and re-run it when the server killed its plan (see
+      # {MONGO_QUERY_PLAN_KILLED_CODE}). Only wraps reads: re-running a
+      # find or aggregate that returned nothing has no side effects. Each
+      # retry emits `parse.mongodb.query_killed_retry`.
+      #
+      # @param collection_name [String] for the notification payload.
+      # @yieldreturn [Object] the read's result.
+      def with_query_killed_retry(collection_name)
+        attempts = 0
+        begin
+          yield
+        rescue StandardError => e
+          raise unless query_plan_killed?(e) && attempts < QUERY_KILLED_RETRIES
+          attempts += 1
+          ActiveSupport::Notifications.instrument(
+            "parse.mongodb.query_killed_retry",
+            collection: collection_name.to_s, attempt: attempts,
+          )
+          retry
+        end
+      end
+
+      # @return [Boolean] true when `err` is the driver's report of a
+      #   killed query plan. Matches the numeric code first and the code
+      #   name second, since older response-parsing paths have surfaced
+      #   only one of the two.
+      def query_plan_killed?(err)
+        return false unless defined?(::Mongo::Error::OperationFailure)
+        return false unless err.is_a?(::Mongo::Error::OperationFailure)
+        return true if err.respond_to?(:code) && err.code == MONGO_QUERY_PLAN_KILLED_CODE
+        err.respond_to?(:code_name) && err.code_name == "QueryPlanKilled"
+      end
+
       # Inspect a driver exception and raise {ExecutionTimeout} if it carries
       # error code 50 (MaxTimeMSExpired). Otherwise, the original exception is
       # re-raised by the caller.

data/lib/parse/query.rb

@@ -2439,11 +2439,11 @@ module Parse
       original_limit = @limit
       @limit = count
 
-      begin
-        items = results_direct
-      ensure
-        @limit = original_limit
-      end
+      items = begin
+          results_direct
+        ensure
+          @limit = original_limit
+        end
 
       count == 1 ? items.first : items.first(count)
     end

data/lib/parse/retrieval/reranker/voyage.rb

@@ -0,0 +1,282 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "ipaddr"
+require_relative "../reranker"
+
+module Parse
+  module Retrieval
+    module Reranker
+      # Voyage AI cross-encoder reranker. Wraps `POST /v1/rerank`.
+      #
+      # Takes a query plus a list of document strings and returns a
+      # relevance-ordered list of `{ index, relevance_score }` objects.
+      # It is a distinct endpoint from `/v1/embeddings`; do NOT confuse it
+      # with {Parse::Embeddings::Voyage} (the embeddings provider).
+      #
+      # == Endpoints
+      #
+      # The same models are served by Voyage's own API and by MongoDB's
+      # Atlas Embedding and Reranking API, with an identical wire contract.
+      # An Atlas model API key (prefix {ATLAS_KEY_PREFIX}) routes to
+      # {ATLAS_BASE_URL} automatically, matching the embeddings provider.
+      # Pass `base_url:` to target either host (or a proxy) explicitly.
+      #
+      # The HTTP stack mirrors {Cohere}: explicit `proxy: nil` unless
+      # opted in, bounded timeouts, capped retries with backoff on
+      # 429/5xx, a response-size cap, and a redacted `#inspect`.
+      #
+      # @example
+      #   reranker = Parse::Retrieval::Reranker::Voyage.new(
+      #     api_key: ENV.fetch("VOYAGE_API_KEY"),
+      #     model:   "rerank-3",
+      #   )
+      #   reranker.rerank(query: "rain songs", documents: lyrics, top_n: 5)
+      class Voyage < Base
+        class AuthenticationError < Error; end
+        class RateLimitError < Error; end
+        class TransientError < Error; end
+        class BadRequestError < Error; end
+
+        DEFAULT_BASE_URL = "https://api.voyageai.com/v1"
+        ATLAS_BASE_URL = "https://ai.mongodb.com/v1"
+        # Atlas model API keys carry this prefix and authenticate only
+        # against {ATLAS_BASE_URL}.
+        ATLAS_KEY_PREFIX = "al-"
+        DEFAULT_MODEL = "rerank-3"
+        DEFAULT_TIMEOUT = 30
+        DEFAULT_OPEN_TIMEOUT = 5
+        DEFAULT_MAX_RETRIES = 2
+
+        # Current and still-served rerank models. Informational: the
+        # constructor accepts any non-empty model name so a newly released
+        # model works without an SDK upgrade.
+        MODELS = %w[rerank-3 rerank-3-lite rerank-2.5 rerank-2.5-lite rerank-2 rerank-2-lite].freeze
+
+        # Voyage documents a cap of 1000 documents per rerank call; the
+        # {Base::MAX_DOCUMENTS} cap (1000) already enforces this.
+        MAX_RESPONSE_BYTES = 5 * 1024 * 1024
+
+        # @param api_key [String] Voyage API key, or an Atlas model API key.
+        # @param model [String] rerank model (default {DEFAULT_MODEL}).
+        # @param base_url [String, nil] API base. Defaults to
+        #   {ATLAS_BASE_URL} for an Atlas key, else {DEFAULT_BASE_URL}.
+        # @param truncation [Boolean] forward Voyage's `truncation:` field.
+        #   Defaults `true` (Voyage's default). `false` makes over-length
+        #   inputs a 400 instead of silently truncating them.
+        # @param timeout [Integer] read timeout (seconds).
+        # @param open_timeout [Integer] connect timeout (seconds).
+        # @param max_retries [Integer] retry budget for 429 / 5xx /
+        #   transient connection errors.
+        # @param allow_faraday_proxy [Boolean] permit Faraday to honor
+        #   `*_proxy` env vars (default false, explicit `proxy: nil`).
+        def initialize(api_key:, model: DEFAULT_MODEL, base_url: nil, truncation: true,
+                       timeout: DEFAULT_TIMEOUT, open_timeout: DEFAULT_OPEN_TIMEOUT,
+                       max_retries: DEFAULT_MAX_RETRIES, allow_faraday_proxy: false)
+          validate_api_key!(api_key)
+          @api_key = api_key
+          @model = model.to_s
+          raise ArgumentError, "Reranker::Voyage: model must be non-empty." if @model.empty?
+          base_url ||= api_key.start_with?(ATLAS_KEY_PREFIX) ? ATLAS_BASE_URL : DEFAULT_BASE_URL
+          @base_url = base_url.to_s
+          validate_base_url!(@base_url)
+          unless [true, false].include?(truncation)
+            raise ArgumentError, "Reranker::Voyage: truncation must be true or false (got #{truncation.inspect})."
+          end
+          @truncation = truncation
+          @timeout = Integer(timeout)
+          @open_timeout = Integer(open_timeout)
+          @max_retries = Integer(max_retries)
+          raise ArgumentError, "Reranker::Voyage: max_retries must be >= 0." if @max_retries.negative?
+          @allow_faraday_proxy = allow_faraday_proxy ? true : false
+          @connection = build_connection
+        end
+
+        # @return [String] the rerank model name.
+        attr_reader :model
+
+        # @return [Boolean] true when routed through {ATLAS_BASE_URL}.
+        def atlas?
+          safe_base_host == URI.parse(ATLAS_BASE_URL).host
+        end
+
+        def inspect
+          "#<#{self.class} model=#{@model.inspect} base=#{safe_base_host.inspect} " \
+          "retries=#{@max_retries} api_key=[REDACTED]>"
+        end
+
+        protected
+
+        def rerank_scores(query, documents, top_n)
+          require_faraday!
+          body = {
+            "model" => @model,
+            "query" => query,
+            "documents" => documents,
+            "top_k" => top_n,
+            "truncation" => @truncation,
+          }
+          payload = post_rerank(body)
+          extract_results!(payload)
+        end
+
+        private
+
+        def post_rerank(body)
+          attempts = 0
+          loop do
+            attempts += 1
+            begin
+              response = @connection.post("rerank") { |req| req.body = body.to_json }
+            rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+              raise TransientError, "Reranker::Voyage: #{e.class} after #{attempts} attempt(s)." if attempts > @max_retries
+              sleep(backoff_seconds(attempts))
+              next
+            end
+
+            status = response.status
+            return parse_json_body!(response.body) if status >= 200 && status < 300
+
+            case status
+            when 401
+              raise AuthenticationError, "Reranker::Voyage: 401 Unauthorized. Check api_key."
+            when 403
+              # Voyage and Atlas keys are not interchangeable; a key sent to
+              # the other host is refused with a 403.
+              raise AuthenticationError,
+                    "Reranker::Voyage: 403 Forbidden from #{safe_base_host}. Atlas model API keys " \
+                    "(#{ATLAS_KEY_PREFIX}...) work only against #{ATLAS_BASE_URL}, and Voyage keys only " \
+                    "against #{DEFAULT_BASE_URL}; check that base_url matches the key."
+            when 429
+              raise RateLimitError, "Reranker::Voyage: 429 rate limited after #{attempts} attempt(s)." if attempts > @max_retries
+              sleep(retry_after_seconds(response) || backoff_seconds(attempts))
+            when 500..599
+              raise TransientError, "Reranker::Voyage: #{status} after #{attempts} attempt(s)." if attempts > @max_retries
+              sleep(backoff_seconds(attempts))
+            else
+              raise BadRequestError, "Reranker::Voyage: #{status} from POST /rerank."
+            end
+          end
+        end
+
+        # Voyage /v1/rerank response shape:
+        #   { "object": "list",
+        #     "data": [ { "index": 0, "relevance_score": 0.45 }, ... ],
+        #     "model": "rerank-3", "usage": { "total_tokens": 8 } }
+        def extract_results!(payload)
+          unless payload.is_a?(Hash)
+            raise InvalidResponseError, "Reranker::Voyage: response body is not a JSON object."
+          end
+          data = payload["data"]
+          unless data.is_a?(Array)
+            raise InvalidResponseError, "Reranker::Voyage: response.data is not an Array."
+          end
+          data.map do |r|
+            unless r.is_a?(Hash)
+              raise InvalidResponseError, "Reranker::Voyage: rerank result is not an object (#{r.inspect})."
+            end
+            Result.new(index: r["index"], relevance_score: r["relevance_score"])
+          end
+        end
+
+        def parse_json_body!(body)
+          s = body.to_s
+          if s.bytesize > MAX_RESPONSE_BYTES
+            raise InvalidResponseError,
+                  "Reranker::Voyage: response body exceeds #{MAX_RESPONSE_BYTES} bytes (#{s.bytesize})."
+          end
+          JSON.parse(s, max_nesting: 32)
+        rescue JSON::ParserError => e
+          raise InvalidResponseError, "Reranker::Voyage: response is not valid JSON (#{e.message})."
+        end
+
+        def build_connection
+          require_faraday!
+          headers = {
+            "Authorization" => "Bearer #{@api_key}",
+            "Content-Type" => "application/json",
+            "Accept" => "application/json",
+            "User-Agent" => "parse-stack-reranker/#{Parse::Stack::VERSION rescue "0"}",
+          }
+          # base_url must end with a trailing slash so Faraday resolves the
+          # relative "rerank" path under /v1/ rather than replacing it.
+          base = @base_url.end_with?("/") ? @base_url : "#{@base_url}/"
+          faraday_opts = { url: base, headers: headers }
+          faraday_opts[:proxy] = nil unless @allow_faraday_proxy
+          conn = Faraday.new(**faraday_opts) do |f|
+            f.options.timeout = @timeout
+            f.options.open_timeout = @open_timeout
+            f.adapter Faraday.default_adapter
+          end
+          conn.proxy = nil if !@allow_faraday_proxy && conn.respond_to?(:proxy=)
+          conn
+        end
+
+        def backoff_seconds(attempt)
+          [0.5 * (2 ** (attempt - 1)), 30.0].min
+        end
+
+        def retry_after_seconds(response)
+          ra = response.respond_to?(:headers) ? response.headers["retry-after"] || response.headers["Retry-After"] : nil
+          return nil unless ra
+          v = ra.to_f
+          v.positive? ? [v, 60.0].min : nil
+        end
+
+        def validate_api_key!(api_key)
+          unless api_key.is_a?(String) && !api_key.empty?
+            raise ArgumentError, "Reranker::Voyage: api_key must be a non-empty String."
+          end
+        end
+
+        def validate_base_url!(base_url)
+          uri = URI.parse(base_url)
+          unless uri.is_a?(URI::HTTPS) || uri.is_a?(URI::HTTP)
+            raise ArgumentError, "Reranker::Voyage: base_url must be http(s) (got #{base_url.inspect})."
+          end
+          # Credentials in the URL leak into logs and error messages, and
+          # userinfo can mask the real host.
+          unless uri.userinfo.nil?
+            raise ArgumentError,
+                  "Reranker::Voyage: base_url must not embed userinfo (credentials in the URL)."
+          end
+          # Plaintext http:// would send the API key in the clear. Permit it
+          # only for loopback hosts (a local dev proxy or sidecar).
+          if uri.scheme == "http" && !loopback_host?(uri.host)
+            raise ArgumentError,
+                  "Reranker::Voyage: base_url must be https:// for non-loopback hosts " \
+                  "(refusing to send the API key over plaintext http to #{uri.host.inspect})."
+          end
+        rescue URI::InvalidURIError => e
+          raise ArgumentError, "Reranker::Voyage: invalid base_url #{base_url.inspect} (#{e.message})."
+        end
+
+        # @return [Boolean] true for localhost / 127.0.0.0/8 / ::1 etc.
+        def loopback_host?(host)
+          return false if host.nil? || host.empty?
+          h = host.downcase.sub(/\A\[/, "").sub(/\]\z/, "")
+          return true if h == "localhost"
+          begin
+            IPAddr.new(h).loopback?
+          rescue IPAddr::Error
+            false
+          end
+        end
+
+        def safe_base_host
+          URI.parse(@base_url).host
+        rescue StandardError
+          "?"
+        end
+
+        def require_faraday!
+          require "faraday" unless defined?(Faraday)
+        rescue LoadError
+          raise Error, "Reranker::Voyage requires the `faraday` gem."
+        end
+      end
+    end
+  end
+end

data/lib/parse/retrieval/reranker.rb

@@ -37,6 +37,8 @@ module Parse
       # The Cohere `/v2/rerank` adapter is loaded lazily — it requires
       # Faraday, which the core retrieval path does not.
       autoload :Cohere, ::File.expand_path("reranker/cohere", __dir__)
+      # The Voyage `/v1/rerank` adapter, also lazy for the same reason.
+      autoload :Voyage, ::File.expand_path("reranker/voyage", __dir__)
 
       # Base error for the reranker layer. Adapters raise subclasses.
       class Error < StandardError; end

data/lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.7.3"
+    VERSION = "5.7.5"
   end
 end

data/parse-stack-next.gemspec

@@ -71,6 +71,7 @@ Gem::Specification.new do |spec|
   # Required for: Parse::MongoDB, Parse::AtlasSearch, mongo_direct query methods
   # Users can add this to their Gemfile for direct MongoDB access:
   #   gem 'mongo', '~> 2.18'
+  # Use mongo 2.26 or newer against MongoDB 9.0 servers.
   # Note: The gem is loaded at runtime only when MongoDB features are used
 
   # Optional dependency for GraphQL schema type generation

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parse-stack-next
 version: !ruby/object:Gem::Version
-  version: 5.7.3
+  version: 5.7.5
 platform: ruby
 authors:
 - Adrian Curtin
@@ -251,6 +251,7 @@ files:
 - lib/parse/agent/constraint_translator.rb
 - lib/parse/agent/describe.rb
 - lib/parse/agent/errors.rb
+- lib/parse/agent/log_levels.rb
 - lib/parse/agent/mcp_client.rb
 - lib/parse/agent/mcp_dispatcher.rb
 - lib/parse/agent/mcp_rack_app.rb
@@ -406,6 +407,7 @@ files:
 - lib/parse/retrieval/chunker.rb
 - lib/parse/retrieval/reranker.rb
 - lib/parse/retrieval/reranker/cohere.rb
+- lib/parse/retrieval/reranker/voyage.rb
 - lib/parse/retrieval/retriever.rb
 - lib/parse/schema.rb
 - lib/parse/schema/index_migrator.rb