Class: Parse::Embeddings::Provider Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/parse/embeddings/provider.rb

Overview

This class is abstract.

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:

Direct Known Subclasses

Cohere, Fixture, Jina, LocalHTTP, OpenAI, Qwen, Voyage

Constant Summary collapse

AS_NOTIFICATION_NAME =

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.

"parse.embeddings.embed"

Instance Method Summary collapse

Instance Method Details

#dimensions ⇒ Integer

Returns fixed output width of this provider's vectors.

Returns:

  • (Integer) —

    fixed output width of this provider's vectors.

Raises:

  • (NotImplementedError) 


97
98
99
 
# File 'lib/parse/embeddings/provider.rb', line 97

def dimensions
  raise NotImplementedError, "#{self.class}#dimensions must be implemented"
end

#embed_batch_size ⇒ Integer?

Returns provider-recommended batch size, or nil.

Returns:

  • (Integer, nil) —

    provider-recommended batch size, or nil.



113
114
115
 
# File 'lib/parse/embeddings/provider.rb', line 113

def embed_batch_size
  nil
end

#embed_image(sources, input_type: :search_document, allow_insecure: false, **opts) ⇒ Array<Array<Float>>

Returns vectors aligned 1:1 with sources.

Parameters:

  • sources (Array<URI, IO, String>) —

    image sources — URI for remote, IO for streamed bytes, String for base64. Concrete providers document which forms they accept. In v5.1 (URL-only path), every source is a raw String URL forwarded unchanged from the managed path: Core::EmbedManaged deliberately does NOT validate before calling the provider (validating there would double-resolve every URL). The concrete embed_image override is therefore responsible for calling Parse::Embeddings.validate_image_url! (passing allow_insecure: through) before egress — see the bundled Voyage/Cohere providers, which validate internally.

  • input_type (Symbol) (defaults to: :search_document) —

    :search_query or :search_document, parallel to #embed_text.

  • allow_insecure (Boolean) (defaults to: false) —

    contract kwarg — Core::EmbedManaged.recompute_embedding! unconditionally forwards this from the directive declaration. Concrete embed_image overrides MUST either accept allow_insecure: explicitly (passing it through to Parse::Embeddings.validate_image_url!) or absorb it via **opts. Dropping **opts from the override signature without accepting allow_insecure: will raise ArgumentError: unknown keyword: allow_insecure from the managed-embedding save path. Default false.

  • opts (Hash) —

    provider-specific options (e.g. dim: for Matryoshka-style truncation). Forward-compatible escape hatch.

Returns:

  • (Array<Array<Float>>) —

    vectors aligned 1:1 with sources.

Raises:

  • (NotImplementedError) —

    image embedding is a v5.1+ feature.



69
70
71
 
# File 'lib/parse/embeddings/provider.rb', line 69

def embed_image(sources, input_type: :search_document, allow_insecure: false, **opts)
  raise NotImplementedError, "#{self.class} does not support image embedding"
end

#embed_text(strings, input_type: :search_document) ⇒ Array<Array<Float>>

Returns vectors aligned 1:1 with strings.

Returns:

  • (Array<Array<Float>>) —

    vectors aligned 1:1 with strings.

Raises:

  • (NotImplementedError) —

    when the concrete subclass has not overridden the method.



38
39
40
 
# File 'lib/parse/embeddings/provider.rb', line 38

def embed_text(strings, input_type: :search_document)
  raise NotImplementedError, "#{self.class}#embed_text must be implemented"
end

#embed_text_batched(strings, input_type: :search_document) ⇒ Array<Array<Float>>

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.

Parameters:

Returns:

  • (Array<Array<Float>>) —

    aligned 1:1 with strings.



83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/parse/embeddings/provider.rb', line 83

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

#inspect ⇒ Object

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.



193
194
195
196
 
# File 'lib/parse/embeddings/provider.rb', line 193

def inspect
  attrs = inspect_attrs.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
  attrs.empty? ? "#<#{self.class}>" : "#<#{self.class} #{attrs}>"
end

#inspect_attrs ⇒ Hash

Returns attributes safe to surface in #inspect. Override in subclasses to add fields; never add credentials.

Returns:

  • (Hash) —

    attributes safe to surface in #inspect. Override in subclasses to add fields; never add credentials.



200
201
202
203
204
205
 
# File 'lib/parse/embeddings/provider.rb', line 200

def inspect_attrs
  out = {}
  out[:model] = safe_call(:model_name)
  out[:dim]   = safe_call(:dimensions)
  out.compact
end

#instrument_embed(input_count, input_type, **extra) ⇒ Object

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.



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/parse/embeddings/provider.rb', line 243

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

#max_input_tokens ⇒ Integer?

Returns chunker hint; max tokens per input.

Returns:

  • (Integer, nil) —

    chunker hint; max tokens per input.



118
119
120
 
# File 'lib/parse/embeddings/provider.rb', line 118

def max_input_tokens
  nil
end

#modalities ⇒ Array<Symbol>

Returns subset of [:text, :image, :audio, :video].

Returns:

  • (Array<Symbol>) —

    subset of [:text, :image, :audio, :video].



108
109
110
 
# File 'lib/parse/embeddings/provider.rb', line 108

def modalities
  [:text]
end

#model_name ⇒ String

Returns stable model identifier (e.g. "text-embedding-3-small"). Used as a cache-key component and persisted to embedding_meta.

Returns:

  • (String) —

    stable model identifier (e.g. "text-embedding-3-small"). Used as a cache-key component and persisted to embedding_meta.

Raises:

  • (NotImplementedError) 


103
104
105
 
# File 'lib/parse/embeddings/provider.rb', line 103

def model_name
  raise NotImplementedError, "#{self.class}#model_name must be implemented"
end

#normalize? ⇒ Boolean

Returns whether the provider returns unit-normalized vectors. Affects similarity-metric selection (:cosine vs :dotProduct).

Returns:

  • (Boolean) —

    whether the provider returns unit-normalized vectors. Affects similarity-metric selection (:cosine vs :dotProduct).



125
126
127
 
# File 'lib/parse/embeddings/provider.rb', line 125

def normalize?
  false
end

#supports_input_type? ⇒ Boolean

Returns 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.

Returns:

  • (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.



133
134
135
 
# File 'lib/parse/embeddings/provider.rb', line 133

def supports_input_type?
  false
end

#validate_response!(input_count, vectors) ⇒ Array<Array<Float>>

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.

Parameters:

  • input_count (Integer) —

    number of items in the input batch.

  • vectors (Array<Array<Float>>) —

    the provider's response.

Returns:

  • (Array<Array<Float>>) —

    vectors, unchanged on success.

Raises:



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/parse/embeddings/provider.rb', line 152

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