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 “nn”, 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