parse-stack-next 5.7.3 → 5.7.5

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/client.rb

@@ -1424,6 +1424,30 @@ module Parse
           retry
         end
         raise
+      rescue Faraday::ConnectionFailed => e
+        # `Faraday::ConnectionFailed` covers two very different failures under
+        # one class, so it is split on the wrapped cause (see
+        # #connection_reset_error?):
+        #
+        #   - RESET mid-flight (`Errno::ECONNRESET` / `Errno::EPIPE` /
+        #     `Errno::ECONNABORTED` / `EOFError`): the classic stale
+        #     keep-alive failure. A pooled persistent connection idled past
+        #     the server's (or an LB's) keep-alive window and was closed
+        #     remotely, and the next request on it dies at the socket.
+        #     Transient by nature (a fresh connection succeeds immediately),
+        #     so it retries under the same idempotency rules as a read
+        #     timeout: the outcome is unknown, so only idempotent requests
+        #     are re-sent.
+        #
+        #   - REFUSED (and DNS failure): the server is down or misconfigured.
+        #     Retrying only adds backoff latency and `[Parse:Retry]` noise
+        #     before the inevitable error, so it propagates raw and fast.
+        raise unless connection_reset_error?(e)
+        if _retry_count > 0 && idempotent_retry?(method, body, headers)
+          _retry_count = consume_retry_with_backoff(_retry_count, _retry_max, _request)
+          retry
+        end
+        raise Parse::Error::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
       rescue Faraday::ClientError, Faraday::TimeoutError, Net::OpenTimeout => e
         # Request timed out mid-flight: the outcome is unknown (the server may
         # have received and applied the write but never answered), so only
@@ -1431,25 +1455,74 @@ module Parse
         #
         # Faraday 2.x raises `Faraday::TimeoutError` for a read timeout
         # (`Timeout::Error` / `Errno::ETIMEDOUT`); it subclasses `Faraday::Error`,
-        # not `ClientError`, so it must be listed explicitly to be caught. We
-        # deliberately do NOT catch `Faraday::ConnectionFailed` (connection
-        # refused/reset, plus the wrapped connect-timeout): refused is a
-        # non-transient "server down / misconfigured" failure, and auto-retrying
-        # it only adds backoff latency before the inevitable error. Broadening to
-        # reset connections safely (retry reset, fail fast on refused) is tracked
-        # as a follow-up.
+        # not `ClientError`, so it must be listed explicitly to be caught.
+        # `Faraday::ConnectionFailed` is handled in its own rescue above,
+        # split into retry-reset / fail-fast-refused.
         if _retry_count > 0 && idempotent_retry?(method, body, headers)
-          warn "[Parse:Retry] Retries remaining #{_retry_count} : #{_request}"
-          _retry_count -= 1
-          backoff_delay = RETRY_DELAY * (_retry_max - _retry_count)
-          _retry_delay = backoff_delay * (0.75 + rand * 0.5)
-          sleep _retry_delay if _retry_delay > 0
+          _retry_count = consume_retry_with_backoff(_retry_count, _retry_max, _request)
           retry
         end
         raise Parse::Error::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
       end
     end
 
+    # Consumes one attempt from the retry budget: logs the remaining count,
+    # sleeps the linear backoff (RETRY_DELAY x attempt number, +/-25% jitter,
+    # never zero), and returns the decremented budget. Shared by the
+    # connection-reset and timeout rescue branches in {#request} so their
+    # backoff behavior cannot drift apart; the `retry` keyword itself must
+    # stay lexically inside each rescue clause, so it remains at the call
+    # sites. The 429/503 branch keeps its own inline version because it also
+    # honors a server-supplied Retry-After header.
+    # @param retry_count [Integer] the remaining retry budget (must be > 0).
+    # @param retry_max [Integer] the effective starting budget.
+    # @param request [Parse::Request] the request being retried (for logging).
+    # @return [Integer] the decremented retry budget.
+    def consume_retry_with_backoff(retry_count, retry_max, request)
+      warn "[Parse:Retry] Retries remaining #{retry_count} : #{request}"
+      retry_count -= 1
+      backoff_delay = RETRY_DELAY * (retry_max - retry_count)
+      retry_delay = backoff_delay * (0.75 + rand * 0.5)
+      sleep retry_delay if retry_delay > 0
+      retry_count
+    end
+
+    # The wrapped causes that mark a `Faraday::ConnectionFailed` as a RESET
+    # connection (transient, retry-safe for idempotent requests) rather than a
+    # REFUSED one (server down, fail fast). `EOFError` is what net/http raises
+    # when the remote end closes a keep-alive socket cleanly between requests;
+    # ECONNRESET/EPIPE/ECONNABORTED are the unclean variants.
+    # @!visibility private
+    CONNECTION_RESET_CAUSES = [
+      Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED, EOFError,
+    ].freeze
+
+    # Message fallback for adapters that raise `Faraday::ConnectionFailed`
+    # with the cause flattened into the message instead of wrapped.
+    # @!visibility private
+    CONNECTION_RESET_MESSAGE = /connection reset|broken pipe|end of file reached/i
+
+    # Whether a `Faraday::ConnectionFailed` was caused by a reset/dropped
+    # connection (retryable) as opposed to connection-refused or a DNS
+    # failure (fail fast). Walks the wrapped exception and the `#cause`
+    # chain looking for a reset-class error.
+    # @param error [Exception] the rescued `Faraday::ConnectionFailed`.
+    # @return [Boolean]
+    def connection_reset_error?(error)
+      inner = error.respond_to?(:wrapped_exception) ? error.wrapped_exception : nil
+      inner ||= error.cause
+      seen = 0
+      while inner && seen < 8
+        return true if CONNECTION_RESET_CAUSES.any? { |klass| inner.is_a?(klass) }
+        inner = inner.cause
+        seen += 1
+      end
+      CONNECTION_RESET_MESSAGE.match?(error.message.to_s)
+    end
+
+    private :consume_retry_with_backoff, :connection_reset_error?
+    private_constant :CONNECTION_RESET_CAUSES, :CONNECTION_RESET_MESSAGE
+
     # Whether a request whose outcome is UNKNOWN (a 500/503 or a dropped
     # connection) is safe to transparently re-send.
     #

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