Module: Parse::Core::EmbedManaged

Included in:
Object
Defined in:
lib/parse/model/core/embed_managed.rb

Overview

Class-level embed macro for :vector properties.

Lets a model declare which scalar fields feed into a managed embedding, and arranges for that embedding to be computed automatically on save whenever the source fields change.

Mechanics

The class macro:

  1. Validates that into: names a declared :vector property with provider: metadata.
  2. Auto-declares a <into>_digest :string sibling property (override with digest_field:).
  3. Registers a before_save callback that re-computes the embedding whenever the SHA-256 of the concatenated source fields differs from the stored digest. On first save the digest is blank and the embedding is always populated. On a save where no source field changed the digest matches and the callback is a no-op (zero provider calls).
  4. Prepends a guard module that raises ProtectedFieldError on direct body_embedding= assignment from user code. The guard lifts only inside the managed write path (the before_save callback itself).

Provider calls flow through Embeddings.provider — the provider is resolved by name at save time, so registering a provider can happen any time before the first save. Declaration never makes a network call.

Single vector per record (v5.0)

embed produces exactly one vector per record. All declared source fields are concatenated (joined with "\n\n", blank values skipped) and sent to the provider as a single string. There is no built-in chunker in v5.0: long source text whose concatenation exceeds the provider's per-call token budget will be truncated provider-side, and the resulting vector will represent only the leading portion of the document.

If your source text is long-form (full articles, long transcripts, multi-page PDFs), you have two options in v5.0:

  1. Pre-chunk client-side and write each chunk as its own Parse::Object record with its own embed declaration.
  2. Maintain a dedicated Chunk subclass that belongs_to the parent record, with embed :content, into: :embedding on the chunk class itself.

A built-in chunker + semantic_search agent tool are scheduled for v5.1.

Examples:

class Document < Parse::Object
  property :title, :string
  property :body,  :string
  property :body_embedding, :vector, dimensions: 1536, provider: :openai
  embed :title, :body, into: :body_embedding
end

doc = Document.new(title: "hello", body: "world")
doc.save   # provider :openai is called once; body_embedding populated

Defined Under Namespace

Modules: ClassMethods Classes: EmbedDirective, InvalidEmbedDeclaration, ProtectedFieldError

Constant Summary collapse

WRITER_KEY =

Internal: name of the Thread-local key under which the managed writer marks the symbol of the field it is currently writing. The guard module's setter checks this key to permit a single field write; the guard is otherwise closed.

:parse_embed_managed_writer