parse-stack-next 5.7.4 → 5.7.6

data/lib/parse/agent.rb

@@ -21,6 +21,7 @@ require_relative "agent/result_formatter"
 require_relative "agent/pipeline_validator"
 require_relative "agent/rate_limiter"
 require_relative "agent/cancellation_token"
+require_relative "agent/log_levels"
 require_relative "agent/approval_gate"
 require_relative "agent/prompt_hardening"
 require_relative "agent/describe"
@@ -1002,6 +1003,15 @@ module Parse
     #   Numeric. `total` and `message` are optional.
     attr_accessor :progress_callback
 
+    # @return [#call, nil] callback that emits MCP `notifications/message`
+    #   log events. Installed per request by Parse::Agent::MCPDispatcher on
+    #   streaming transports, which drop messages below the level the
+    #   client set with `logging/setLevel`. When nil, {#log} is a no-op.
+    #   Application code should log through {#log}, not this accessor.
+    #
+    #   The callback signature is `call(level:, data:, logger:)`.
+    attr_accessor :log_callback
+
     # @return [Parse::Agent::CancellationToken, nil] cooperative
     #   cancellation token installed by Parse::Agent::MCPDispatcher around
     #   tool dispatch when the transport supports cancellation
@@ -1319,6 +1329,35 @@ module Parse
       nil
     end
 
+    # Emit an MCP log message to the connected client. Tools (built-in or
+    # registered through `Parse::Agent::Tools.register`) call this to
+    # surface diagnostics without failing the call. The message reaches
+    # the client only on a streaming transport and only when the client
+    # asked for this level or a lower one via `logging/setLevel`;
+    # otherwise this is a no-op.
+    #
+    # @param level [Symbol, String] an RFC 5424 severity: `:debug`,
+    #   `:info`, `:notice`, `:warning`, `:error`, `:critical`, `:alert`,
+    #   or `:emergency`.
+    # @param data [Object] any JSON-serializable value. Do not include
+    #   secrets or data the agent's scope may not see.
+    # @param logger [String, nil] optional logger name shown by the client.
+    # @return [void]
+    # @raise [ArgumentError] for an unknown level.
+    def log(level, data, logger: nil)
+      # Validate before the no-callback return so a bad level fails the
+      # same way on every transport, not only on a streaming request.
+      level = level.to_s
+      unless LOG_LEVELS.include?(level)
+        raise ArgumentError, "log level must be one of #{LOG_LEVELS.join(", ")} (got #{level.inspect})"
+      end
+      cb = @log_callback
+      return if cb.nil?
+
+      cb.call(level: level, data: data, logger: logger)
+      nil
+    end
+
     # @return [Integer] total prompt tokens used across all requests
     attr_reader :total_prompt_tokens
 
@@ -1719,6 +1758,7 @@ module Parse
         # client is observing.
         @cancellation_token = parent.cancellation_token
         @progress_callback = parent.progress_callback
+        @log_callback = parent.log_callback
 
         # Clamp the sub-agent's permission tier at the parent's. The
         # default :readonly is always ≤ any parent tier, so this fires

data/lib/parse/atlas_search.rb

@@ -1067,7 +1067,11 @@ module Parse
         if (mode = Parse::MongoDB.send(:normalize_read_preference, read_preference))
           coll = coll.with(read: { mode: mode })
         end
-        coll.aggregate(pipeline, agg_opts).to_a
+        # Same QueryPlanKilled re-run as Parse::MongoDB.aggregate (private
+        # there too, hence `send`).
+        Parse::MongoDB.send(:with_query_killed_retry, collection_name) do
+          coll.aggregate(pipeline, agg_opts).to_a
+        end
       rescue => e
         # `raise_if_timeout!` is module-private on Parse::MongoDB; use
         # `send` so we can reuse the timeout-translation logic without

data/lib/parse/embeddings/cache.rb

@@ -8,7 +8,7 @@ require "json"
 module Parse
   module Embeddings
     # Process-local embedding cache keyed by
-    # `(provider, model, input_type, input_hash)`.
+    # `(provider, model, dimensions, input_type, deployment, input_hash)`.
     #
     # Query-side embedding is the hot repeat path: the same natural-
     # language query (an agent retrying a tool call, a user paging
@@ -32,7 +32,10 @@ module Parse
     #
     # == Key derivation
     #
-    # `provider.class.name | model_name | input_type | SHA-256(input)`.
+    # `provider.class.name | model_name | dimensions | input_type |
+    # cache_identity | SHA-256(input)`. `cache_identity` (the provider's
+    # endpoint without credentials, see {Provider#cache_identity}) is
+    # omitted for providers that have none.
     # The full input text never becomes part of the key, so a shared
     # external store does not accumulate plaintext queries.
     #
@@ -305,8 +308,8 @@ module Parse
         # @!visibility private
         # Composite cache key. The input is hashed so plaintext never
         # lands in a shared store; provider identity + model + dimensions
-        # + input_type namespace the hash (two models' vectors are never
-        # confused). Dimensions matter independently of the model name:
+        # + input_type + deployment namespace the hash (two models' or two
+        # deployments' vectors are never confused). Dimensions matter independently of the model name:
         # Matryoshka-capable providers (OpenAI text-embedding-3-*, Cohere
         # embed-v4, Voyage, Jina, Qwen) can register the same model at
         # different output widths, and serving one width's cached vector
@@ -322,7 +325,16 @@ module Parse
             rescue NotImplementedError
               "unknown"
             end
-          "#{provider.class.name}|#{model}|#{dims}|#{input_type}|#{Digest::SHA256.hexdigest(input.to_s)}"
+          # Deployment identity (endpoint, never credentials) separates two
+          # deployments of the same model. Omitted when the provider has
+          # none, so such providers keep their existing keys.
+          identity = begin
+              provider.respond_to?(:cache_identity) ? provider.cache_identity : nil
+            rescue StandardError
+              nil
+            end
+          deployment = identity.nil? || identity.to_s.empty? ? "" : "#{identity}|"
+          "#{provider.class.name}|#{model}|#{dims}|#{input_type}|#{deployment}#{Digest::SHA256.hexdigest(input.to_s)}"
         end
 
         # @!visibility private

data/lib/parse/embeddings/provider.rb

@@ -1,6 +1,8 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require "uri"
+
 module Parse
   module Embeddings
     # Abstract base class for embedding providers. Concrete subclasses
@@ -242,6 +244,30 @@ module Parse
 
       # @return [Hash] attributes safe to surface in {#inspect}. Override
       #   in subclasses to add fields; never add credentials.
+      # Identity of the deployment this provider talks to, for use in cache
+      # keys: the endpoint's scheme, host, non-default port, and path. Never
+      # includes credentials, userinfo, or a query string. Two providers of
+      # the same class and model pointed at different deployments (two
+      # self-hosted servers, or a provider behind a proxy) can return
+      # different vectors for the same input, so their cache entries must
+      # not be shared.
+      #
+      # The default reads `@base_url`, which every built-in HTTP provider
+      # sets. A provider with no configurable endpoint returns nil, which
+      # leaves its cache key unchanged. Override to supply another identity.
+      #
+      # @return [String, nil]
+      def cache_identity
+        url = instance_variable_defined?(:@base_url) ? @base_url : nil
+        return nil if url.nil? || url.to_s.empty?
+        uri = URI.parse(url.to_s)
+        return nil if uri.host.nil? || uri.host.empty?
+        port = uri.port && uri.port != uri.default_port ? ":#{uri.port}" : ""
+        "#{uri.scheme}://#{uri.host.downcase}#{port}#{uri.path.to_s.chomp("/")}"
+      rescue URI::InvalidURIError
+        nil
+      end
+
       def inspect_attrs
         out = {}
         out[:model] = safe_call(:model_name)

data/lib/parse/embeddings/voyage.rb

@@ -9,9 +9,11 @@ require_relative "provider"
 module Parse
   module Embeddings
     # Voyage AI embeddings provider. Wraps `POST /v1/embeddings` for
-    # text-only models and `POST /v1/multimodalembeddings` for the
+    # text-only models, `POST /v1/multimodalembeddings` for the
     # multimodal text+image models (text via {#embed_text}, images via
-    # {#embed_image}).
+    # {#embed_image}), and `POST /v1/contextualizedembeddings` for the
+    # contextualized chunk models (single texts via {#embed_text},
+    # whole chunked documents via {#embed_chunks}).
     #
     # Supported models:
     #
@@ -21,7 +23,8 @@ module Parse
     #   llama.cpp).
     # * **v3 family** — `voyage-3-large`, `voyage-3.5`,
     #   `voyage-3.5-lite`, `voyage-3`, `voyage-3-lite`.
-    # * **code models** — `voyage-code-3`, `voyage-code-2` (1536-dim).
+    # * **code models**: `voyage-code-4`, `voyage-code-3`, and
+    #   `voyage-code-2` (the only 1536-dim one).
     # * **domain models** — `voyage-finance-2`, `voyage-law-2`.
     # * **multimodal** — `voyage-multimodal-3` (text+image) and
     #   `voyage-multimodal-3.5` (text+image+video). Unified vector
@@ -31,6 +34,14 @@ module Parse
     #   {#embed_image}, video through {#embed_video}. All three share
     #   the same space, so stored text vectors are comparable against
     #   image and video vectors without re-embedding.
+    # * **contextualized chunk**: `voyage-context-4` and
+    #   `voyage-context-3`. Each chunk's vector also encodes the
+    #   document it came from, so chunks are embedded a document at a
+    #   time through {#embed_chunks}. {#embed_text} sends every string
+    #   as a one-chunk document. That is the right shape for queries, and it
+    #   is also what the `embed` macro and {BatchEmbedder} send for stored
+    #   fields, so those vectors carry no surrounding-document context;
+    #   call {#embed_chunks} directly for chunk-level context.
     #
     # Audio is not offered by any Voyage model, and neither PDF nor
     # DOCX is accepted as a content type — render document pages to
@@ -127,6 +138,13 @@ module Parse
       DEFAULT_BATCH_SIZE = 128
       MAX_RESPONSE_BYTES = 16 * 1024 * 1024
 
+      # Upper bounds on the JSON size of one returned vector, used to plan
+      # contextualized requests: a float such as `-1.2345678901234567e-05,`
+      # is under 32 bytes, and the `{"object":"embedding","embedding":[],
+      # "index":N}` wrapper is under 256.
+      RESPONSE_BYTES_PER_VALUE = 32
+      RESPONSE_BYTES_PER_VECTOR_ENVELOPE = 256
+
       # Default (native) vector width per model — the width returned
       # when `output_dimension` is omitted from the request.
       #
@@ -147,12 +165,15 @@ module Parse
         "voyage-3.5-lite" => 1024,
         "voyage-3" => 1024,
         "voyage-3-lite" => 512,
+        "voyage-code-4" => 1024,
         "voyage-code-3" => 1024,
         "voyage-code-2" => 1536,
         "voyage-finance-2" => 1024,
         "voyage-law-2" => 1024,
         "voyage-multimodal-3" => 1024,
         "voyage-multimodal-3.5" => 1024,
+        "voyage-context-4" => 1024,
+        "voyage-context-3" => 1024,
       }.freeze
 
       # Every width a model's Matryoshka head will actually return.
@@ -174,12 +195,15 @@ module Parse
         "voyage-3.5-lite" => [256, 512, 1024, 2048],
         "voyage-3" => [1024],
         "voyage-3-lite" => [512],
+        "voyage-code-4" => [256, 512, 1024, 2048],
         "voyage-code-3" => [256, 512, 1024, 2048],
         "voyage-code-2" => [1536],
         "voyage-finance-2" => [1024],
         "voyage-law-2" => [1024],
         "voyage-multimodal-3" => [1024],
         "voyage-multimodal-3.5" => [256, 512, 1024, 2048],
+        "voyage-context-4" => [256, 512, 1024, 2048],
+        "voyage-context-3" => [256, 512, 1024, 2048],
       }.freeze
 
       # Back-compat alias: the set of models accepting any
@@ -198,12 +222,17 @@ module Parse
         "voyage-3.5-lite" => 32_000,
         "voyage-3" => 32_000,
         "voyage-3-lite" => 32_000,
+        "voyage-code-4" => 32_000,
         "voyage-code-3" => 32_000,
         "voyage-code-2" => 16_000,
         "voyage-finance-2" => 32_000,
         "voyage-law-2" => 16_000,
         "voyage-multimodal-3" => 32_000,
         "voyage-multimodal-3.5" => 32_000,
+        # Per document (one inner list of chunks). The request as a
+        # whole is capped at 120k tokens across every document.
+        "voyage-context-4" => 32_000,
+        "voyage-context-3" => 32_000,
       }.freeze
 
       # Models that route to `/v1/multimodalembeddings` with the
@@ -226,6 +255,27 @@ module Parse
       # "does not support video inputs" 400.
       VIDEO_MODELS = %w[voyage-multimodal-3.5].freeze
 
+      # Models that route to `/v1/contextualizedembeddings` with the
+      # `{ inputs: [[chunk, ...], ...] }` envelope: one inner list per
+      # document, each chunk embedded with the rest of its document as
+      # context. The endpoint has no `truncation` field, so it is never
+      # sent for these models.
+      CONTEXTUALIZED_MODELS = %w[voyage-context-4 voyage-context-3].freeze
+
+      # Voyage's per-request limits for the contextualized endpoint:
+      # at most this many documents, and this many chunks summed
+      # across them.
+      # The endpoint also caps a request at 120k tokens summed across
+      # every document, which the SDK cannot check without a tokenizer.
+      MAX_CONTEXT_DOCUMENTS = 1_000
+      MAX_CONTEXT_CHUNKS = 16_000
+
+      # Default `embed_batch_size` for {CONTEXTUALIZED_MODELS}. Each
+      # string is a whole document there, so 128 paragraph-sized inputs
+      # would overrun the 120k-token request cap; 32 leaves room for
+      # documents averaging under about 3,700 tokens.
+      CONTEXT_DEFAULT_BATCH_SIZE = 32
+
       # Models Voyage's hosted API serves but the Atlas Embedding and
       # Reranking API does not. Verified against both endpoints.
       ATLAS_UNAVAILABLE_MODELS = %w[voyage-3 voyage-3-lite].freeze
@@ -271,11 +321,13 @@ module Parse
       # @param timeout [Integer] read timeout, seconds.
       # @param open_timeout [Integer] connect timeout, seconds.
       # @param max_retries [Integer] retry attempts on 429/5xx/timeouts.
-      # @param embed_batch_size [Integer] inputs per request (max 128).
+      # @param embed_batch_size [Integer, nil] inputs per request (max 128).
+      #   Defaults to {DEFAULT_BATCH_SIZE}, or {CONTEXT_DEFAULT_BATCH_SIZE}
+      #   for a contextualized model.
       # @param dimensions [Integer, nil] override output width via
-      #   Voyage's `output_dimension` Matryoshka parameter. Only
-      #   `voyage-4-large` accepts the field; for every other model the
-      #   override must equal the native width or be omitted.
+      #   Voyage's `output_dimension` Matryoshka parameter. Must be one of
+      #   the model's {MODEL_SUPPORTED_DIMENSIONS}; a model with a single
+      #   supported width accepts only that width (or nil).
       # @param truncation [Boolean] forward Voyage's `truncation:` field.
       #   Defaults `true` to match Voyage's API default. Set `false` to
       #   force the API to reject over-length inputs rather than silently
@@ -292,7 +344,7 @@ module Parse
         timeout: DEFAULT_TIMEOUT,
         open_timeout: DEFAULT_OPEN_TIMEOUT,
         max_retries: DEFAULT_MAX_RETRIES,
-        embed_batch_size: DEFAULT_BATCH_SIZE,
+        embed_batch_size: nil,
         dimensions: nil,
         truncation: true,
         allow_faraday_proxy: false,
@@ -308,6 +360,7 @@ module Parse
         validate_positive_integer!(:timeout, timeout)
         validate_positive_integer!(:open_timeout, open_timeout)
         validate_non_negative_integer!(:max_retries, max_retries)
+        embed_batch_size ||= CONTEXTUALIZED_MODELS.include?(model) ? CONTEXT_DEFAULT_BATCH_SIZE : DEFAULT_BATCH_SIZE
         validate_positive_integer!(:embed_batch_size, embed_batch_size)
         if embed_batch_size > 128
           raise ArgumentError,
@@ -396,10 +449,22 @@ module Parse
         end
         wire_input_type = INPUT_TYPE_WIRE_VALUES[input_type]
 
+        if CONTEXTUALIZED_MODELS.include?(@model)
+          if strings.length > MAX_CONTEXT_DOCUMENTS
+            raise ArgumentError,
+                  "Parse::Embeddings::Voyage#embed_text: #{strings.length} inputs exceeds Voyage's " \
+                  "per-request cap for #{@model} (#{MAX_CONTEXT_DOCUMENTS}). Split the input."
+          end
+          # Each string is its own one-chunk document, so the response
+          # carries exactly one vector per document.
+          return embed_contextualized(strings.map { |s| [s] }, input_type, wire_input_type).map(&:first)
+        end
+
         # Multimodal models route to a different endpoint with a
         # different request envelope. The response envelope shape is
         # the same (`{ data: [{ embedding, index }], usage: {...} }`)
         # so `extract_vectors!` is reused as-is.
+
         body = if MULTIMODAL_MODELS.include?(@model)
             build_multimodal_body(strings, wire_input_type)
           else
@@ -500,6 +565,72 @@ module Parse
                              allow_insecure: allow_insecure)
       end
 
+      # Embed chunked documents through Voyage's
+      # `/v1/contextualizedembeddings` endpoint. Every chunk's vector
+      # encodes the surrounding document as well as the chunk itself,
+      # so pass the chunks of one document together, in order, rather
+      # than one call per chunk.
+      #
+      # **Contextualized model required.** Only {CONTEXTUALIZED_MODELS}
+      # accept this shape; any other model raises {BadRequestError}
+      # before any network call.
+      #
+      # @param documents [Array<Array<String>>] one inner Array per
+      #   document, holding that document's chunks in order. At most
+      #   {MAX_CONTEXT_DOCUMENTS} documents and {MAX_CONTEXT_CHUNKS}
+      #   chunks in total.
+      # @param input_type [Symbol] one of {INPUT_TYPE_WIRE_VALUES}'s keys.
+      # @return [Array<Array<Array<Float>>>] one Array of chunk vectors
+      #   per document, aligned 1:1 with `documents` and with each
+      #   document's chunks.
+      def embed_chunks(documents, input_type: :search_document)
+        unless CONTEXTUALIZED_MODELS.include?(@model)
+          raise BadRequestError,
+                "Parse::Embeddings::Voyage#embed_chunks: model #{@model.inspect} does not " \
+                "accept chunked documents. Configure the provider with a contextualized model " \
+                "(supported: #{CONTEXTUALIZED_MODELS.inspect})."
+        end
+        unless documents.is_a?(Array)
+          raise ArgumentError,
+                "Parse::Embeddings::Voyage#embed_chunks expects Array<Array<String>> " \
+                "(got #{documents.class})."
+        end
+        return [] if documents.empty?
+
+        documents.each_with_index do |chunks, i|
+          unless chunks.is_a?(Array) && !chunks.empty?
+            raise ArgumentError,
+                  "Parse::Embeddings::Voyage#embed_chunks documents[#{i}] must be a non-empty " \
+                  "Array of chunk Strings."
+          end
+          chunks.each_with_index do |c, j|
+            unless c.is_a?(String) && !c.empty?
+              raise ArgumentError,
+                    "Parse::Embeddings::Voyage#embed_chunks documents[#{i}][#{j}] must be a " \
+                    "non-empty String."
+            end
+          end
+        end
+        if documents.length > MAX_CONTEXT_DOCUMENTS
+          raise ArgumentError,
+                "Parse::Embeddings::Voyage#embed_chunks: #{documents.length} documents exceeds " \
+                "Voyage's per-request cap (#{MAX_CONTEXT_DOCUMENTS}). Split the input."
+        end
+        chunk_total = documents.sum(&:length)
+        if chunk_total > MAX_CONTEXT_CHUNKS
+          raise ArgumentError,
+                "Parse::Embeddings::Voyage#embed_chunks: #{chunk_total} chunks exceeds " \
+                "Voyage's per-request cap (#{MAX_CONTEXT_CHUNKS}). Split the input."
+        end
+        unless INPUT_TYPE_WIRE_VALUES.key?(input_type)
+          raise ArgumentError,
+                "Parse::Embeddings::Voyage#embed_chunks input_type #{input_type.inspect} not in " \
+                "#{INPUT_TYPE_WIRE_VALUES.keys.inspect}."
+        end
+
+        embed_contextualized(documents, input_type, INPUT_TYPE_WIRE_VALUES[input_type])
+      end
+
       def inspect_attrs
         super.merge(base: safe_base_host, endpoint: @endpoint, retries: @max_retries)
       end
@@ -561,6 +692,68 @@ module Parse
         body
       end
 
+      # Build the wire body for `/v1/contextualizedembeddings`. The
+      # endpoint documents no `truncation` field, so none is sent.
+      def build_contextualized_body(documents, wire_input_type)
+        body = { inputs: documents, model: @model }
+        body[:input_type] = wire_input_type if wire_input_type
+        apply_output_dimension!(body)
+        body
+      end
+
+      # Embed documents through the contextualized endpoint and return one
+      # Array of chunk vectors per document, in input order.
+      #
+      # Voyage accepts up to {MAX_CONTEXT_CHUNKS} chunks per request, but
+      # that many vectors serialize to far more than {MAX_RESPONSE_BYTES}.
+      # Whole documents are therefore grouped so each response's estimated
+      # size stays within the cap, and the groups are sent in turn. A
+      # single document too large for the cap on its own is sent alone
+      # with a response allowance sized to its chunk count.
+      def embed_contextualized(documents, input_type, wire_input_type)
+        per_vector = response_bytes_per_vector
+        chunks_per_request = [MAX_RESPONSE_BYTES / per_vector, 1].max
+        groups = []
+        documents.each do |doc|
+          last = groups.last
+          if last && last.sum(&:length) + doc.length <= chunks_per_request
+            last << doc
+          else
+            groups << [doc]
+          end
+        end
+        groups.flat_map { |group| embed_contextualized_request(group, input_type, wire_input_type) }
+      end
+
+      # @return [Integer] the planning estimate for one vector's JSON size.
+      def response_bytes_per_vector
+        (@dimensions * RESPONSE_BYTES_PER_VALUE) + RESPONSE_BYTES_PER_VECTOR_ENVELOPE
+      end
+
+      # Issue one contextualized request and return one Array of chunk
+      # vectors per document.
+      def embed_contextualized_request(documents, input_type, wire_input_type)
+        body = build_contextualized_body(documents, wire_input_type)
+        chunk_count = documents.sum(&:length)
+        allowance = [MAX_RESPONSE_BYTES, (chunk_count * response_bytes_per_vector) + 65_536].max
+
+        instrument_embed(chunk_count, input_type) do |emit_payload|
+          payload = post_embeddings(body, path: "contextualizedembeddings", max_response_bytes: allowance)
+          if payload.is_a?(Hash) && payload["usage"].is_a?(Hash)
+            tt = payload["usage"]["total_tokens"]
+            emit_payload[:total_tokens] = tt if tt.is_a?(Integer) && tt >= 0
+          end
+          # The response nests the standard envelope: the outer `data`
+          # holds one `{ data: [...], index: }` list per document, and
+          # each inner list is shaped like a `/v1/embeddings` response.
+          per_document = extract_vectors!(payload, documents.length, value_key: "data")
+          per_document.each_with_index.map do |entry, i|
+            vectors = extract_vectors!({ "data" => entry }, documents[i].length)
+            validate_response!(documents[i].length, vectors)
+          end
+        end
+      end
+
       # Forward `output_dimension` only when the configured width
       # differs from the model's native default. Sending it to a model
       # with a single supported width is a 400, and sending the native
@@ -792,7 +985,9 @@ module Parse
         encoded[0...-1]
       end
 
-      def post_embeddings(body, path: "embeddings")
+      # @param max_response_bytes [Integer] refuse a success body larger than
+      #   this. Defaults to {MAX_RESPONSE_BYTES}.
+      def post_embeddings(body, path: "embeddings", max_response_bytes: MAX_RESPONSE_BYTES)
         attempts = 0
         loop do
           attempts += 1
@@ -820,7 +1015,7 @@ module Parse
           end
 
           status = response.status
-          return parse_json_body!(response.body) if status >= 200 && status < 300
+          return parse_json_body!(response.body, max_response_bytes) if status >= 200 && status < 300
 
           if status == 401
             raise AuthenticationError,
@@ -847,11 +1042,11 @@ module Parse
         end
       end
 
-      def parse_json_body!(body)
+      def parse_json_body!(body, max_bytes = MAX_RESPONSE_BYTES)
         s = body.to_s
-        if s.bytesize > MAX_RESPONSE_BYTES
+        if s.bytesize > max_bytes
           raise InvalidResponseError,
-                "Parse::Embeddings::Voyage: response body exceeds #{MAX_RESPONSE_BYTES} bytes " \
+                "Parse::Embeddings::Voyage: response body exceeds #{max_bytes} bytes " \
                 "(#{s.bytesize}). Refusing to parse."
         end
         JSON.parse(s, max_nesting: 32)
@@ -871,7 +1066,11 @@ module Parse
       #     "model": "voyage-3",
       #     "usage": { "total_tokens": N }
       #   }
-      def extract_vectors!(payload, input_count)
+      #
+      # `value_key` names the field read from each entry: `"embedding"`
+      # for the flat envelope, `"data"` for the outer list of the
+      # contextualized envelope.
+      def extract_vectors!(payload, input_count, value_key: "embedding")
         unless payload.is_a?(Hash)
           raise InvalidResponseError,
                 "Parse::Embeddings::Voyage: response body is not a JSON object."
@@ -895,7 +1094,7 @@ module Parse
             raise InvalidResponseError,
                   "Parse::Embeddings::Voyage: response.data[#{i}].index #{idx.inspect} out of range."
           end
-          [idx, entry["embedding"]]
+          [idx, entry[value_key]]
         end
         indices = sorted.map(&:first)
         if indices.uniq.length != indices.length

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.