parse-stack-next 4.5.0 → 5.0.1

data/lib/parse/embeddings/provider.rb

@@ -0,0 +1,264 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module Embeddings
+    # Abstract base class for embedding providers. Concrete subclasses
+    # implement {#embed_text} (and, in v5.1+, optionally {#embed_image}).
+    #
+    # Provider responsibilities:
+    #
+    # * Translate a batch of inputs into a batch of float vectors.
+    # * Return vectors in **the same order** as inputs.
+    # * Call {#validate_response!} before returning so the caller sees
+    #   a typed {InvalidResponseError} for off-by-one batches and NaN /
+    #   ±Inf poisoning at the provider boundary — not deep inside a
+    #   later $vectorSearch call.
+    #
+    # Subclasses MUST override:
+    #
+    # * {#embed_text} — `(strings, input_type:) -> Array<Array<Float>>`
+    # * {#dimensions} — `Integer`, the fixed output width
+    # * {#model_name} — stable identifier for cache keys / `embedding_meta`
+    #
+    # Subclasses MAY override:
+    #
+    # * {#embed_image}      — v5.1 (multimodal); default `NotImplementedError`
+    # * {#embed_batch_size} — provider-recommended batch size hint
+    # * {#max_input_tokens} — chunker hint
+    # * {#normalize?}       — whether output is unit-normalized
+    # * {#modalities}       — defaults to `[:text]`
+    # * {#supports_input_type?} — defaults to `false`
+    #
+    # @abstract
+    class Provider
+      # @return [Array<Array<Float>>] vectors aligned 1:1 with `strings`.
+      # @raise [NotImplementedError] when the concrete subclass has not
+      #   overridden the method.
+      def embed_text(strings, input_type: :search_document)
+        raise NotImplementedError, "#{self.class}#embed_text must be implemented"
+      end
+
+      # @param sources [Array<URI, IO, String>] image sources — URI for
+      #   remote, IO for streamed bytes, String for base64. Concrete
+      #   providers document which forms they accept.
+      # @param input_type [Symbol] `:search_query` or `:search_document`,
+      #   parallel to {#embed_text}.
+      # @param opts [Hash] provider-specific options (e.g. `dim:` for
+      #   Matryoshka-style truncation). Forward-compatible escape hatch.
+      # @return [Array<Array<Float>>] vectors aligned 1:1 with `sources`.
+      # @raise [NotImplementedError] image embedding is a v5.1+ feature.
+      def embed_image(sources, input_type: :search_document, **opts)
+        raise NotImplementedError, "#{self.class} does not support image embedding"
+      end
+
+      # Batched text embedding. Splits `strings` into chunks of size
+      # {#embed_batch_size} (or returns a single-shot call when nil) and
+      # concatenates results. Concrete providers should override only
+      # when their HTTP shape needs more than naive slicing (e.g. async
+      # parallelism, per-request budgets). The default is sufficient for
+      # any provider whose `embed_text` accepts an array directly.
+      #
+      # @param strings [Array<String>]
+      # @param input_type [Symbol]
+      # @return [Array<Array<Float>>] aligned 1:1 with `strings`.
+      def embed_text_batched(strings, input_type: :search_document)
+        unless strings.is_a?(Array)
+          raise ArgumentError,
+                "#{self.class}#embed_text_batched expects Array<String> (got #{strings.class})."
+        end
+        return [] if strings.empty?
+        size = embed_batch_size
+        return embed_text(strings, input_type: input_type) if size.nil? || strings.length <= size
+        strings.each_slice(size).flat_map do |slice|
+          embed_text(slice, input_type: input_type)
+        end
+      end
+
+      # @return [Integer] fixed output width of this provider's vectors.
+      def dimensions
+        raise NotImplementedError, "#{self.class}#dimensions must be implemented"
+      end
+
+      # @return [String] stable model identifier (e.g. "text-embedding-3-small").
+      #   Used as a cache-key component and persisted to `embedding_meta`.
+      def model_name
+        raise NotImplementedError, "#{self.class}#model_name must be implemented"
+      end
+
+      # @return [Array<Symbol>] subset of [:text, :image, :audio, :video].
+      def modalities
+        [:text]
+      end
+
+      # @return [Integer, nil] provider-recommended batch size, or nil.
+      def embed_batch_size
+        nil
+      end
+
+      # @return [Integer, nil] chunker hint; max tokens per input.
+      def max_input_tokens
+        nil
+      end
+
+      # @return [Boolean] whether the provider returns unit-normalized
+      #   vectors. Affects similarity-metric selection (`:cosine` vs
+      #   `:dotProduct`).
+      def normalize?
+        false
+      end
+
+      # @return [Boolean] whether the provider distinguishes between
+      #   `:search_query` and `:search_document` inputs. When false the
+      #   `input_type:` kwarg is accepted (for forward compatibility and
+      #   cache-key stability) but has no effect on the returned vector.
+      def supports_input_type?
+        false
+      end
+
+      # Validate a provider response before returning it from `embed_*`.
+      #
+      # Raises {InvalidResponseError} on any of:
+      #
+      # * `vectors.length != input_count` (off-by-one across batch — the
+      #   most insidious provider bug, since vectors would be silently
+      #   misaligned with their inputs).
+      # * `vectors[i]` is not an Array.
+      # * `vectors[i].length != dimensions` (variable-width response).
+      # * any element non-Numeric, NaN, or ±Inf.
+      #
+      # @param input_count [Integer] number of items in the input batch.
+      # @param vectors [Array<Array<Float>>] the provider's response.
+      # @return [Array<Array<Float>>] vectors, unchanged on success.
+      # @raise [InvalidResponseError]
+      def validate_response!(input_count, vectors)
+        unless vectors.is_a?(Array)
+          raise InvalidResponseError,
+                "#{self.class}: expected Array of vectors, got #{vectors.class}."
+        end
+        if vectors.length != input_count
+          raise InvalidResponseError,
+                "#{self.class}: response length #{vectors.length} != input count #{input_count}."
+        end
+        dims = dimensions
+        vectors.each_with_index do |vec, i|
+          unless vec.is_a?(Array)
+            raise InvalidResponseError,
+                  "#{self.class}: response[#{i}] is not an Array (#{vec.class})."
+          end
+          if vec.length != dims
+            raise InvalidResponseError,
+                  "#{self.class}: response[#{i}] length #{vec.length} != declared dimensions #{dims}."
+          end
+          vec.each_with_index do |x, j|
+            # Strictly Float or Integer. Numeric is too loose — Complex
+            # has #finite? and would pass; Rational/BigDecimal serialize
+            # to BSON in surprising ways. Vector elements are always
+            # floats in practice.
+            unless x.is_a?(Float) || x.is_a?(Integer)
+              raise InvalidResponseError,
+                    "#{self.class}: response[#{i}][#{j}] is not Float or Integer (#{x.class})."
+            end
+            unless x.respond_to?(:finite?) && x.finite?
+              raise InvalidResponseError,
+                    "#{self.class}: response[#{i}][#{j}] is not finite (#{x.inspect})."
+            end
+          end
+        end
+        vectors
+      end
+
+      # Default {#inspect} that allowlists safe instance vars. Concrete
+      # providers holding `@api_key`, `@bearer_token`, etc. inherit a
+      # safe `inspect` automatically. Subclasses may extend the
+      # allowlist by overriding {#inspect_attrs}.
+      def inspect
+        attrs = inspect_attrs.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+        attrs.empty? ? "#<#{self.class}>" : "#<#{self.class} #{attrs}>"
+      end
+
+      # @return [Hash] attributes safe to surface in {#inspect}. Override
+      #   in subclasses to add fields; never add credentials.
+      def inspect_attrs
+        out = {}
+        out[:model] = safe_call(:model_name)
+        out[:dim]   = safe_call(:dimensions)
+        out.compact
+      end
+
+      # AS::N event name emitted from {#instrument_embed}. Subscribers
+      # match this exact string. Parallel namespace to
+      # `parse.mongodb.aggregate` / `parse.cache.*` /
+      # `parse.agent.tool_call` so a single AS::N subscription tree can
+      # cover query, cache, agent, and embedding spend.
+      AS_NOTIFICATION_NAME = "parse.embeddings.embed"
+
+      # Subscribed payload contract. Keys are present on every emit so
+      # subscribers can rely on them without `key?` guards (values may
+      # be `nil` when the provider does not surface usage telemetry —
+      # e.g. {Fixture} has no token cost).
+      #
+      # * `:provider`     [String]  — `self.class.name`
+      # * `:model`        [String]  — {#model_name}
+      # * `:dimensions`   [Integer] — {#dimensions}
+      # * `:input_count`  [Integer] — number of items in the batch
+      # * `:input_type`   [Symbol]  — `:search_query` / `:search_document`
+      # * `:total_tokens` [Integer, nil] — provider-reported token usage; nil when N/A
+      # * `:cached`       [Boolean] — whether the batch was served from cache (always false in v5.0)
+      # * `:error`        [String, nil] — `exception.class.name` when the block raised
+      #
+      # Subscribers should NOT depend on additional keys appearing — the
+      # contract is stable. New keys may be added but existing semantics
+      # will not change without a deprecation cycle.
+      #
+      # Synchronous-subscriber discipline: AS::N delivers events on the
+      # request thread. A slow subscriber blocks every embed call; an
+      # exception in a subscriber surfaces as a request failure. Keep
+      # subscribers cheap (counters, in-memory accumulators) or push to
+      # non-blocking sinks (StatsD-over-UDP, OTel exporters that batch).
+      #
+      # The block is yielded the payload Hash so concrete providers can
+      # write `:total_tokens` / `:cached` from inside the network call
+      # (after parsing the provider's `usage` envelope). Any other field
+      # set on the yielded payload also reaches subscribers — but only
+      # via the documented keys above. Stick to the contract.
+      def instrument_embed(input_count, input_type, **extra)
+        payload = {
+          provider: self.class.name,
+          model: safe_call(:model_name),
+          dimensions: safe_call(:dimensions),
+          input_count: input_count,
+          input_type: input_type,
+          total_tokens: nil,
+          cached: false,
+          error: nil,
+        }.merge(extra)
+        # Defensive: AS::N is in active_support, which the wider gem
+        # already requires; if a downstream caller has loaded the
+        # embeddings module without ActiveSupport (e.g. a sliced
+        # require of just `parse/embeddings`), fall through.
+        unless defined?(ActiveSupport::Notifications)
+          return yield(payload)
+        end
+        result = nil
+        ActiveSupport::Notifications.instrument(AS_NOTIFICATION_NAME, payload) do |emit_payload|
+          begin
+            result = yield(emit_payload)
+          rescue StandardError => e
+            emit_payload[:error] = e.class.name
+            raise
+          end
+        end
+        result
+      end
+
+      private
+
+      def safe_call(method)
+        public_send(method)
+      rescue NotImplementedError
+        nil
+      end
+    end
+  end
+end

data/lib/parse/embeddings/qwen.rb

@@ -0,0 +1,431 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "uri"
+require_relative "provider"
+
+module Parse
+  module Embeddings
+    # Qwen 3 embeddings provider. Targets Alibaba Cloud DashScope's
+    # OpenAI-compatible endpoint (`/compatible-mode/v1/embeddings`),
+    # which mirrors the OpenAI request envelope but speaks the
+    # `qwen3-embedding-*` model family.
+    #
+    # Supported models — all three are Matryoshka-capable, so the
+    # `dimensions:` constructor kwarg truncates the returned vector
+    # to any width ≤ native:
+    #
+    # * `qwen3-embedding-0.6b` — 1024 dim native, ~32k input tokens.
+    # * `qwen3-embedding-4b`   — 2560 dim native.
+    # * `qwen3-embedding-8b`   — 4096 dim native.
+    #
+    # The same three checkpoints are published open-weight on Hugging
+    # Face under Apache 2.0 (`Qwen/Qwen3-Embedding-0.6B`, etc.) — for
+    # self-hosted inference behind vLLM / Text Embeddings Inference /
+    # llama.cpp, use {LocalHTTP} instead and point it at your gateway.
+    #
+    # @example registration (DashScope International endpoint)
+    #   Parse::Embeddings.register(:qwen,
+    #     Parse::Embeddings::Qwen.new(
+    #       api_key: ENV.fetch("DASHSCOPE_API_KEY"),
+    #       model:   "qwen3-embedding-8b",
+    #     ))
+    #
+    # @example Matryoshka truncation
+    #   Parse::Embeddings::Qwen.new(
+    #     api_key: ENV.fetch("DASHSCOPE_API_KEY"),
+    #     model:      "qwen3-embedding-8b",
+    #     dimensions: 1024,  # truncate from 4096 → 1024
+    #   )
+    #
+    # == Asymmetric input types
+    #
+    # Qwen3-Embedding is trained with an instruction-tuned head, but
+    # the DashScope compatible-mode endpoint does not currently accept
+    # an `input_type` / `task` request field. We therefore set
+    # `supports_input_type?` to `false` and drop the SDK-canonical
+    # `input_type:` kwarg at the wire — same posture as {OpenAI} and
+    # {LocalHTTP}. Callers who want query/passage asymmetry must wrap
+    # their text with an explicit instruction prefix client-side; the
+    # AS::N event still carries the requested `input_type` so cache
+    # keys remain stable.
+    class Qwen < Provider
+      class AuthenticationError < Error; end
+      class BadRequestError < Error; end
+      class RateLimitError < Error; end
+      class TransientError < Error; end
+
+      # Default to the international compatible-mode host. Operators
+      # in mainland China should override to
+      # `https://dashscope.aliyuncs.com/compatible-mode/v1`.
+      DEFAULT_BASE_URL    = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+      DEFAULT_MODEL       = "qwen3-embedding-8b"
+      DEFAULT_TIMEOUT     = 30
+      DEFAULT_OPEN_TIMEOUT = 5
+      DEFAULT_MAX_RETRIES = 3
+      # DashScope's compatible endpoint caps embedding requests at 25
+      # inputs per call (smaller than OpenAI's 2048). Default below
+      # the cap so callers don't have to tune.
+      DEFAULT_BATCH_SIZE  = 10
+      MAX_RESPONSE_BYTES  = 16 * 1024 * 1024
+
+      MODEL_DEFAULT_DIMENSIONS = {
+        "qwen3-embedding-0.6b" => 1024,
+        "qwen3-embedding-4b"   => 2560,
+        "qwen3-embedding-8b"   => 4096,
+      }.freeze
+
+      MODEL_MAX_INPUT_TOKENS = {
+        "qwen3-embedding-0.6b" => 32_000,
+        "qwen3-embedding-4b"   => 32_000,
+        "qwen3-embedding-8b"   => 32_000,
+      }.freeze
+
+      # Every Qwen3-Embedding row is Matryoshka-capable. Kept as an
+      # explicit allowlist so future non-Matryoshka additions (e.g.
+      # qwen-text-embedding-v3) don't silently inherit the behaviour.
+      MATRYOSHKA_MODELS = %w[
+        qwen3-embedding-0.6b
+        qwen3-embedding-4b
+        qwen3-embedding-8b
+      ].freeze
+
+      # @param api_key [String] required. Sent as `Authorization: Bearer …`.
+      # @param model [String] one of {MODEL_DEFAULT_DIMENSIONS}'s keys.
+      # @param dimensions [Integer, nil] Matryoshka truncation. Must
+      #   be ≤ the model's native width.
+      # @param base_url [String] override (mainland-China host or a
+      #   private gateway). Must be HTTPS unless
+      #   `allow_insecure_base_url: true`.
+      # @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 (DashScope
+      #   compatible-mode caps at 25).
+      # @param allow_faraday_proxy [Boolean] opt in to proxy / env-proxy
+      #   autodiscovery. Defaults `false`.
+      # @param allow_insecure_base_url [Boolean] permit `http://` base.
+      # @param connection [Faraday::Connection, nil] injection seam.
+      def initialize(
+        api_key:,
+        model: DEFAULT_MODEL,
+        dimensions: nil,
+        base_url: DEFAULT_BASE_URL,
+        timeout: DEFAULT_TIMEOUT,
+        open_timeout: DEFAULT_OPEN_TIMEOUT,
+        max_retries: DEFAULT_MAX_RETRIES,
+        embed_batch_size: DEFAULT_BATCH_SIZE,
+        allow_faraday_proxy: false,
+        allow_insecure_base_url: false,
+        connection: nil
+      )
+        validate_api_key!(api_key)
+        validate_model!(model)
+        validate_dimensions!(model, dimensions)
+        sanitized_base_url = validate_base_url!(base_url, allow_insecure_base_url)
+        validate_positive_integer!(:timeout, timeout)
+        validate_positive_integer!(:open_timeout, open_timeout)
+        validate_non_negative_integer!(:max_retries, max_retries)
+        validate_positive_integer!(:embed_batch_size, embed_batch_size)
+
+        @api_key = api_key
+        @model = model
+        @dimensions = dimensions || MODEL_DEFAULT_DIMENSIONS.fetch(model)
+        @base_url = sanitized_base_url
+        @timeout = timeout
+        @open_timeout = open_timeout
+        @max_retries = max_retries
+        @embed_batch_size = embed_batch_size
+        @allow_faraday_proxy = allow_faraday_proxy
+        @connection = connection || build_connection
+      end
+
+      def dimensions
+        @dimensions
+      end
+
+      def model_name
+        @model
+      end
+
+      def embed_batch_size
+        @embed_batch_size
+      end
+
+      def max_input_tokens
+        MODEL_MAX_INPUT_TOKENS[@model]
+      end
+
+      def normalize?
+        # Qwen3-Embedding is documented unit-normalized at the head.
+        true
+      end
+
+      def supports_input_type?
+        # DashScope compatible-mode does not accept a wire-level
+        # input_type / task field. The kwarg threads through for
+        # cache-key stability but is dropped at the request.
+        false
+      end
+
+      # @param strings [Array<String>] inputs.
+      # @param input_type [Symbol] accepted for forward compatibility,
+      #   dropped at the wire (see {#supports_input_type?}).
+      # @return [Array<Array<Float>>] vectors aligned 1:1 with `strings`.
+      def embed_text(strings, input_type: :search_document)
+        unless strings.is_a?(Array)
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen#embed_text expects Array<String> (got #{strings.class})."
+        end
+        return [] if strings.empty?
+        strings.each_with_index do |s, i|
+          unless s.is_a?(String)
+            raise ArgumentError,
+                  "Parse::Embeddings::Qwen#embed_text strings[#{i}] is not a String (#{s.class})."
+          end
+          if s.empty?
+            raise ArgumentError,
+                  "Parse::Embeddings::Qwen#embed_text strings[#{i}] is empty; Qwen rejects empty inputs."
+          end
+        end
+
+        body = {
+          model: @model,
+          input: strings,
+          encoding_format: "float",
+        }
+        # Forward `dimensions` only when active width differs from
+        # native. Sending native width is a no-op on DashScope but
+        # we keep the wire minimal to avoid drift across future
+        # endpoint revisions.
+        if MATRYOSHKA_MODELS.include?(@model) &&
+           @dimensions != MODEL_DEFAULT_DIMENSIONS.fetch(@model)
+          body[:dimensions] = @dimensions
+        end
+
+        instrument_embed(strings.length, input_type) do |emit_payload|
+          payload = post_embeddings(body)
+          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
+          vectors = extract_vectors!(payload, strings.length)
+          validate_response!(strings.length, vectors)
+        end
+      end
+
+      def inspect_attrs
+        super.merge(base: safe_base_host, retries: @max_retries)
+      end
+
+      protected
+
+      def build_connection
+        headers = {
+          "Authorization" => "Bearer #{@api_key}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "User-Agent" => "parse-stack-embeddings/#{user_agent_version}",
+        }
+
+        faraday_opts = { url: @base_url, 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 post_embeddings(body)
+        attempts = 0
+        loop do
+          attempts += 1
+          begin
+            response = @connection.post("embeddings") do |req|
+              req.body = body.to_json
+            end
+          rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+            if attempts > @max_retries
+              raise TransientError, "Parse::Embeddings::Qwen: #{e.class} after #{attempts} attempt(s)."
+            end
+            sleep(backoff_seconds(attempts))
+            next
+          end
+
+          status = response.status
+          return parse_json_body!(response.body) if status >= 200 && status < 300
+
+          if status == 401
+            raise AuthenticationError, "Parse::Embeddings::Qwen: 401 Unauthorized — check api_key."
+          end
+          if status == 429
+            if attempts > @max_retries
+              raise RateLimitError, "Parse::Embeddings::Qwen: 429 rate limited after #{attempts} attempt(s)."
+            end
+            sleep(retry_after_seconds(response) || backoff_seconds(attempts))
+            next
+          end
+          if status >= 500
+            if attempts > @max_retries
+              raise TransientError, "Parse::Embeddings::Qwen: #{status} after #{attempts} attempt(s)."
+            end
+            sleep(backoff_seconds(attempts))
+            next
+          end
+          raise BadRequestError, "Parse::Embeddings::Qwen: #{status} from POST /embeddings."
+        end
+      end
+
+      def parse_json_body!(body)
+        s = body.to_s
+        if s.bytesize > MAX_RESPONSE_BYTES
+          raise InvalidResponseError,
+                "Parse::Embeddings::Qwen: response body exceeds #{MAX_RESPONSE_BYTES} bytes " \
+                "(#{s.bytesize}). Refusing to parse."
+        end
+        JSON.parse(s, max_nesting: 32)
+      rescue JSON::ParserError => e
+        raise InvalidResponseError,
+              "Parse::Embeddings::Qwen: response is not valid JSON (#{e.message})."
+      end
+
+      def extract_vectors!(payload, input_count)
+        unless payload.is_a?(Hash)
+          raise InvalidResponseError,
+                "Parse::Embeddings::Qwen: response body is not a JSON object."
+        end
+        data = payload["data"]
+        unless data.is_a?(Array)
+          raise InvalidResponseError,
+                "Parse::Embeddings::Qwen: response.data is not an Array."
+        end
+        if data.length != input_count
+          raise InvalidResponseError,
+                "Parse::Embeddings::Qwen: response.data.length #{data.length} != input count #{input_count}."
+        end
+        sorted = data.each_with_index.map do |entry, i|
+          unless entry.is_a?(Hash)
+            raise InvalidResponseError,
+                  "Parse::Embeddings::Qwen: response.data[#{i}] is not a JSON object."
+          end
+          idx = entry["index"]
+          unless idx.is_a?(Integer) && idx >= 0 && idx < input_count
+            raise InvalidResponseError,
+                  "Parse::Embeddings::Qwen: response.data[#{i}].index #{idx.inspect} out of range."
+          end
+          [idx, entry["embedding"]]
+        end
+        indices = sorted.map(&:first)
+        if indices.uniq.length != indices.length
+          raise InvalidResponseError, "Parse::Embeddings::Qwen: duplicate index in response.data."
+        end
+        sorted.sort_by(&:first).map(&:last)
+      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
+
+      private
+
+      def validate_api_key!(api_key)
+        unless api_key.is_a?(String) && !api_key.empty?
+          raise ArgumentError, "Parse::Embeddings::Qwen: api_key must be a non-empty String."
+        end
+      end
+
+      def validate_model!(model)
+        unless MODEL_DEFAULT_DIMENSIONS.key?(model)
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen: unknown model #{model.inspect}. " \
+                "Supported: #{MODEL_DEFAULT_DIMENSIONS.keys.inspect}."
+        end
+      end
+
+      def validate_dimensions!(model, dimensions)
+        return if dimensions.nil?
+        unless dimensions.is_a?(Integer) && dimensions.positive?
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen: dimensions must be a positive Integer (got #{dimensions.inspect})."
+        end
+        native = MODEL_DEFAULT_DIMENSIONS.fetch(model)
+        if dimensions > native
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen: dimensions #{dimensions} exceeds native #{native} for #{model}."
+        end
+        if !MATRYOSHKA_MODELS.include?(model) && dimensions != native
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen: model #{model.inspect} does not support custom dimensions " \
+                "(Matryoshka-capable models: #{MATRYOSHKA_MODELS.inspect})."
+        end
+      end
+
+      def validate_base_url!(base_url, allow_insecure)
+        unless base_url.is_a?(String) && !base_url.empty?
+          raise ArgumentError, "Parse::Embeddings::Qwen: base_url must be a non-empty String."
+        end
+        begin
+          uri = URI.parse(base_url)
+        rescue URI::InvalidURIError => e
+          raise ArgumentError, "Parse::Embeddings::Qwen: base_url is not a valid URL (#{e.message})."
+        end
+        unless %w[http https].include?(uri.scheme)
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen: base_url must be http(s):// (got scheme #{uri.scheme.inspect})."
+        end
+        if uri.scheme == "http" && !allow_insecure
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen: refusing http:// base_url. Pass allow_insecure_base_url: true to opt in."
+        end
+        if uri.host.nil? || uri.host.empty?
+          raise ArgumentError, "Parse::Embeddings::Qwen: base_url must include a host."
+        end
+        if uri.userinfo
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen: base_url must not contain userinfo (credentials). " \
+                "Use the api_key parameter and a clean URL."
+        end
+        uri.to_s
+      end
+
+      def validate_positive_integer!(name, value)
+        unless value.is_a?(Integer) && value.positive?
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen: #{name} must be a positive Integer (got #{value.inspect})."
+        end
+      end
+
+      def validate_non_negative_integer!(name, value)
+        unless value.is_a?(Integer) && value >= 0
+          raise ArgumentError,
+                "Parse::Embeddings::Qwen: #{name} must be a non-negative Integer (got #{value.inspect})."
+        end
+      end
+
+      def user_agent_version
+        defined?(Parse::Stack::VERSION) ? Parse::Stack::VERSION : "unknown"
+      end
+
+      def safe_base_host
+        uri = URI.parse(@base_url)
+        host = uri.host
+        host && !host.empty? ? "#{uri.scheme}://#{host}" : nil
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+  end
+end