parse-stack-next 5.5.6 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8f26110cea78b4a3fc393dce2ac3aada7d73442f7d1e970e2aa71d88d3ecba2
-  data.tar.gz: 753ead47dcc377ba89e5eca4d2e93a3f7767f5e71a168124f6f180fe7549b5a1
+  metadata.gz: d7ea05ce0688ca7c1df6a1077162478dfee52e33d9fac77c7480c5ca818c9eb8
+  data.tar.gz: 71e61f7e70da94793dae9d741a3e5d29ffc7f9cd45f2adee6c96cd98b5ac2d24
 SHA512:
-  metadata.gz: c1261b7e8db1b2d61e69fe70a1327829afd8d4c1b0960cb1ca1b3d5b418fcbc81b21dc05921a59865d7c226108392f0c3968a982277410872585b5cc4f42760a
-  data.tar.gz: 64f53a649209415edf4c3cecaab383f5ea01e0f106711ae867bfc7ac6d506dde592bd09b628a7956ccb621428ff4cea9c6f5970660d40465581496092b3d18ee
+  metadata.gz: c723fbb9589ce57c7651fab142bed386f3a2070d39fc20887fc40b50f676ccb0041e9b758611e8b75d0a9202095de318ce2bbae35e41015be519209d9d2628dd
+  data.tar.gz: dbbc09ee718630415da1ab329168fc1c10d5d9cf20ad09e4129b2518087231206ca84d7d5ecd5e1a27f66e2fb75d3704b856592fcd43c6d2f7711fa20c0dba1b

data/CHANGELOG.md

@@ -1,5 +1,230 @@
 ## parse-stack-next Changelog
 
+### 5.6.0
+
+#### Voyage embeddings reach the Atlas endpoint, video, and streamed media
+
+- **NEW**: The Voyage provider now targets MongoDB's Atlas Embedding and
+  Reranking API in addition to Voyage's own. The two serve the same models
+  over an identical wire contract but do not share credentials — an Atlas
+  model API key returns 403 from Voyage's host and vice versa. A key carrying
+  the Atlas prefix routes to `https://ai.mongodb.com/v1` automatically; pass
+  `endpoint: :atlas` or `:voyage` to be explicit, or a `base_url:` to override
+  both. A named endpoint that contradicts an explicit `base_url` is rejected
+  rather than silently reconciled, so a credential is never sent to a host the
+  caller did not intend. `#endpoint` and `#atlas?` report the resolved target.
+- **NEW**: Added `voyage-3.5`, `voyage-3.5-lite`, `voyage-code-2` (1536-dim),
+  and `voyage-multimodal-3.5`. Models the Atlas endpoint does not expose —
+  `voyage-3`, `voyage-3-lite`, `voyage-4-nano` — are refused at construction
+  when that endpoint is active, with an error naming a current replacement;
+  they remain valid against Voyage's own API.
+- **NEW**: `Parse::Embeddings::Voyage#embed_video` embeds video through
+  `voyage-multimodal-3.5`, the only model that accepts it. Text, image, and
+  video vectors share one space, so a stored text vector is comparable against
+  a video vector without re-embedding. `#modalities` reports `[:text, :image,
+  :video]` for that model and `[:text, :image]` for `voyage-multimodal-3`.
+- **NEW**: `Parse::Embeddings::MediaFile` wraps a local image or video and
+  streams it into the request body instead of buffering it. Serializing media
+  with `to_json` costs roughly 2.4x the file size resident — raw bytes, the
+  1.33x base64 copy, and the serialized document — which is enough to exhaust
+  a small dyno on a single moderate video. `MediaFile` reads only a 16-byte
+  header at construction; the payload is then base64-encoded into the socket
+  in fixed-size chunks by `Parse::Embeddings::StreamingBody`, so peak memory
+  is bounded by the chunk size regardless of file size and nothing spills to
+  disk. `Content-Length` is computed exactly so the request avoids chunked
+  transfer encoding, and the body replays byte-identically on retry. Passing a
+  URL instead keeps the SDK out of the transfer entirely.
+- **FIXED**: Corrected the model dimension table. The entire v4 family
+  defaults to 1024 — `voyage-4-large`'s 2048, `voyage-4-lite`'s 512, and
+  `voyage-4-nano`'s 256 were recorded as native widths when they are
+  Matryoshka options reached only by requesting them. Because the provider
+  validates the returned vector width against the declared one, both
+  `voyage-4-large` and `voyage-4-lite` raised
+  `Parse::Embeddings::InvalidResponseError` on every call. `voyage-4-nano` is
+  1024, and `voyage-finance-2` carries a 32,000-token context rather than
+  16,000.
+- **CHANGED**: The coarse "Matryoshka-capable models" gate is replaced by
+  per-model `MODEL_SUPPORTED_DIMENSIONS`. Any width on a model's ladder is now
+  accepted — including one wider than its default, which the old rule rejected
+  as "exceeds native" — and a width off the ladder is refused with the
+  supported set named. `output_dimension` is sent whenever the configured
+  width differs from the model's default, so `voyage-4-lite` at 512 and
+  `voyage-4-large` at 2048 both work.
+- **FIXED**: A caller-supplied URL can no longer capture a local file's bytes.
+  The streamed body previously marked each payload with a sentinel token and
+  located it by searching the serialized JSON, so a URL containing that token
+  matched first: the file's base64 was spliced into the URL slot and forwarded
+  to the provider as a URL to fetch, disclosing local file contents, while the
+  intended slot kept the literal token. Request bodies are now assembled
+  structurally — each fragment serialized independently and concatenated in
+  order — so payloads are placed by position and caller data is never
+  searched.
+- **FIXED**: Mixed `image_url` / `image_base64` batches no longer violate
+  Voyage's request contract, which requires a single representation per
+  request. A mixed batch is split into one request per representation and
+  reassembled into the caller's original order, preserving the 1:1 alignment
+  between inputs and returned vectors.
+- **FIXED**: Video validation no longer accepts containers the provider
+  rejects. MP4 is the only format Voyage supports, and WebM and QuickTime
+  payloads are refused by the API, so both are out of the default allowlist.
+  An `ftyp` box no longer implies MP4 on its own — QuickTime and the
+  audio-only profiles share the ISO base media container — so major brands are
+  matched explicitly and an unrecognized brand is refused rather than assumed.
+  Apple's audio-only `M4A` brand is excluded, closing a type confusion in
+  which an audio file passed as video.
+- **NEW**: `Parse::Embeddings.max_media_bytes` caps streamed media per file,
+  defaulting to the 20 MB Voyage documents. Streaming already prevents an
+  oversized file from exhausting memory, but the provider still rejects it, so
+  failing locally turns a wasted upload into an immediate error. The Voyage
+  adapter enforces the 20 MB ceiling independently, so raising the global knob
+  for another provider cannot push an oversized payload onto Voyage.
+
+#### Breaking
+
+- **BREAKING**: The Voyage provider's default model moves from `voyage-3` to
+  `voyage-3.5`. `voyage-3` is retired from the Atlas endpoint, so the old
+  default made an Atlas key fail at construction whenever no model was named.
+  Vectors from the two models are not comparable. **Migration:** code relying
+  on the default must pin `model: "voyage-3"` explicitly to keep existing
+  embeddings valid, or re-embed against the new default. A `:vector` property
+  that declares `model:` is unaffected — the new binding audit catches the
+  mismatch before any request rather than letting the two mix silently.
+
+#### Vector search no longer returns fewer results than requested
+
+- **FIXED**: `$vectorSearch` set its `limit` to `k`, but Atlas applies that
+  limit before the SDK's ACL `$match`, `protectedFields` redaction,
+  pointer-field filtering, and any caller-supplied `filter` — so a scoped
+  caller who could read 2 of the top 10 documents asked for 10 and received 2,
+  even when hundreds of readable matches existed further down the ranking.
+  The search now requests a wider internal candidate window, applies every
+  enforcement layer, and only then trims to `k`. The window is raised only
+  when something can actually drop rows, so a master-key call with no filter
+  keeps its previous one-for-one cost. A `candidate_limit:` option on
+  `VectorSearch.search` and `find_similar` tunes the window for principals
+  whose visibility is unusually narrow. This is a mitigation, not a guarantee:
+  a sufficiently selective ACL can still exhaust any finite window, which is
+  why the attrition counts below exist. HNSW width stays anchored to `k`, so
+  the wider window does not widen the ANN search.
+- **NEW**: `VectorSearch.search` emits a `parse.vector_search.search`
+  `ActiveSupport::Notifications` event carrying `candidate_limit`,
+  `num_candidates`, `post_filter_count`, `post_pointer_count`,
+  `returned_count`, `pointer_attrition`, and `underfilled`. The counts are
+  named for where they are measured — obtaining a true pre-`$match` count
+  would require a `$facet` — so an underfill is observable rather than silent.
+
+#### Vector properties are checked against the provider actually registered
+
+- **FIXED**: A `:vector` property's `model:` was recorded and never enforced.
+  Because models in the same family usually share a width (`voyage-3` and
+  `voyage-3.5` are both 1024), swapping the registered provider's model
+  silently mixed incomparable vectors into one index — no error, just
+  degraded recall, repairable only by re-embedding. `dimensions:` was
+  verified, but only against a vector the provider had already returned and
+  billed for. Both are now checked by `Parse::Embeddings::BindingAudit`
+  before any request is issued, on the managed-write path and the
+  query-embedding path alike. The audit runs ahead of the digest short-circuit
+  so an unchanged record still surfaces a drifted binding, and it fails closed:
+  a provider that cannot report `#model_name` or `#dimensions` is refused
+  rather than skipped, since a declaration that cannot be verified is not a
+  declaration that has been satisfied.
+- **NEW**: `Parse::Embeddings::BindingAudit.audit_all!` and
+  `.audit_all_or_raise!` check every declared binding at once, for a boot-time
+  or CI gate rather than waiting for the first save that happens to touch one.
+- **NEW**: `:vector` properties validate `similarity:` against the functions
+  Atlas accepts (`euclidean`, `cosine`, `dotProduct`) at declaration time
+  instead of surfacing a typo as an index error later.
+- **FIXED**: Hybrid search applies the same candidate window as the plain
+  vector search, so opting into hybrid no longer underfills where a straight
+  vector search would not. Each branch's limit is applied before ACL
+  enforcement and was narrower than the plain path's window.
+- **FIXED**: Hybrid search separates the rows each branch retains for fusion
+  from the rows Atlas considers before ACL. Conflating them meant the branch
+  limit was passed as the vector branch's `k` and then multiplied a second
+  time by the plain search's own window derivation — a hybrid `k: 10` asked
+  Atlas for 1,000 rows instead of the intended 100, an explicit
+  `candidate_limit: 250` became 2,500 on the client path while staying 250 on
+  the native path, and any `k` above 100 produced a branch `k` beyond
+  `VectorSearch::MAX_K` that failed outright. The fusion depth is now bounded
+  by `MAX_K` and the candidate window by Atlas's 10,000 ceiling, with both
+  paths using the same window. A `candidate_limit` outside that range is
+  refused rather than clamped, and `vector: { candidate_limit: }` is forwarded
+  through `hybrid_search`.
+- **FIXED**: The native `$rankFusion` pipeline trimmed to `k` in a `$limit`
+  stage that runs after its ACL `$match`, reintroducing the underfill the
+  candidate window exists to prevent. It now limits to the candidate window
+  and trims to `k` once enforcement has run.
+- **NEW**: A `parse.vector_search.hybrid` notification reports `method`,
+  `branch_depth`, `candidate_window`, `post_filter_count`, `returned_count`,
+  and `underfilled` for both fusion paths. `branch_depth` differs by method by
+  design: the client path enforces ACL inside each branch and can retain the
+  narrower fusion depth, while the native path enforces after `$rankFusion`
+  and must retain the full window. The value reported is the one that ran.
+- **NEW**: A `:vector` property wider than the Atlas vectorSearch index cap is
+  refused unless it declares `searchable: false`. `Parse::Vector` tolerates up
+  to 16384 dimensions while an Atlas index caps at 8192, so such a property
+  was previously declarable, storable, and permanently unsearchable, with the
+  failure appearing only at query time. The two limits remain distinct — they
+  govern storage and indexing respectively — but the combination now has to be
+  acknowledged.
+- **NEW**: `searchable: false` makes a `:vector` property genuinely
+  storage-only, whether it opted out to clear the index cap or by choice. It
+  is excluded from `find_similar` / `hybrid_search` field resolution, refused
+  with an explanation when named directly, and rejected by `agent_searchable`
+  at class load rather than at an agent's first query.
+
+#### Provider protocol
+
+- **NEW**: `Parse::Embeddings::Provider#embed_video` joins `#embed_image` in
+  the base protocol with the same `NotImplementedError` default, so video is a
+  declared capability rather than a Voyage-only method. `#supports_modality?`
+  answers the capability question without rescuing.
+- **NEW**: `rake test:contract` runs live, billable provider contract tests
+  that pin request routing, native dimensions, the Matryoshka ladder, accepted
+  media, size limits, model availability, and response shape. They skip unless
+  `VOYAGE_CONTRACT_KEY` is set and are excluded from both `rake test` and
+  `rake test:unit`, so no ordinary run becomes billable because a key happens
+  to be exported. Probes that assert a refusal issue raw requests rather than
+  going through the SDK — a local guard asserted against itself proves nothing
+  about the contract it encodes — and distinguish a genuine refusal from an
+  authentication, rate-limit, or 5xx failure so infrastructure trouble cannot
+  read as a contract verdict. Mocked tests assert what the SDK believes the
+  API does and therefore cannot detect provider drift: every dimension and
+  media-format correction in this release was invisible to a fully green
+  mocked suite.
+
+### Behavior Notes
+
+- Audio is not offered by any Voyage model, and neither PDF nor DOCX is
+  accepted as a content type. Render document pages to images and embed those;
+  the SDK does not perform that conversion.
+- Deterministic result fill under highly selective ACLs would require the
+  authorization predicate to run inside the Atlas prefilter rather than after
+  it. The post-search `$match` remains the enforcement boundary regardless.
+- `voyage-4-nano` is served by neither hosted endpoint — it is open-weight and
+  meant to be self-hosted. It is refused against Voyage's and Atlas's hosts
+  with a message pointing at a self-hosted `base_url:` or
+  `Parse::Embeddings::LocalHTTP`, and remains usable through either.
+
+### Code Example
+
+```ruby
+# Endpoint inferred from the key prefix — no base_url needed.
+provider = Parse::Embeddings::Voyage.new(
+  api_key: ENV.fetch("ATLAS_MODEL_API_KEY"),
+  model: "voyage-multimodal-3.5",
+)
+provider.endpoint    # => :atlas
+provider.modalities  # => [:text, :image, :video]
+
+# Local media streams into the request; the bytes are never held in memory.
+provider.embed_image([Parse::Embeddings::MediaFile.image("page.png")])
+provider.embed_video([Parse::Embeddings::MediaFile.video("demo.mp4")])
+
+# A URL keeps the SDK out of the transfer entirely — the provider fetches it.
+provider.embed_image(["https://cdn.example.com/page.png"])
+```
+
 ### 5.5.6
 
 #### MCP clients now receive the SSE response instead of hanging

data/lib/parse/agent/metadata_dsl.rb

@@ -634,6 +634,16 @@ module Parse
                   "agent_searchable field: :#{field_sym} is not a declared :vector property " \
                   "on #{parse_class_name} (declared: #{vector_properties.keys.inspect})."
           end
+          # A storage-only property is not eligible for search, so the
+          # tool this registers could never run. Refuse at class load
+          # rather than at the first agent query.
+          if respond_to?(:vector_properties) &&
+             vector_properties.dig(field_sym, :searchable) == false
+            raise ArgumentError,
+                  "agent_searchable field: :#{field_sym} on #{parse_class_name} is declared " \
+                  "`searchable: false` (storage-only, not eligible for search) and cannot " \
+                  "back a search tool."
+          end
           filters = Array(filter_fields).map(&:to_sym)
           @agent_searchable_field = field_sym
           @agent_searchable_filter_fields = filters

data/lib/parse/embeddings/binding_audit.rb

@@ -0,0 +1,211 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module Embeddings
+    # Checks that a `:vector` property's declared provider binding
+    # still matches the provider actually registered under that name.
+    #
+    # A `:vector` property may declare `provider:`, `model:`, and
+    # `dimensions:`. Only `provider:` was ever enforced. `dimensions:`
+    # is verified — but only against the vector a provider already
+    # returned, i.e. after the call has been made and paid for. And
+    # `model:` was never checked at all, which is the dangerous one: two
+    # generations of the same model family usually share a width
+    # (`voyage-3` and `voyage-3.5` are both 1024), so swapping the
+    # registered provider's model silently mixes incompatible
+    # embeddings into one index. Nothing raises, recall just quietly
+    # degrades, and the damage is only repairable by re-embedding.
+    #
+    # This module closes both gaps by comparing the declaration against
+    # the live provider BEFORE any request is issued.
+    #
+    # Auditing cannot happen at class-definition time: providers are
+    # registered by name and, as {Parse::Core::EmbedManaged} documents,
+    # registration may legitimately happen any time before the first
+    # save. So the audit runs lazily on each use and is also exposed as
+    # {.audit_all!} for an explicit boot-time or CI check.
+    module BindingAudit
+      # Raised when a property's declared binding disagrees with the
+      # registered provider.
+      class BindingMismatch < Parse::Embeddings::Error; end
+
+      # Raised when the audit cannot enumerate the classes it is meant
+      # to check. Distinct from {BindingMismatch}: nothing was found to
+      # be wrong, but nothing was verified either.
+      class DiscoveryFailed < Parse::Embeddings::Error; end
+
+      class << self
+        # Verify one property binding against a resolved provider.
+        #
+        # Deliberately NOT memoized. The check is a pair of comparisons
+        # against values already in memory, so caching it saves nothing
+        # measurable — while any cache key cheap enough to be worth
+        # computing (class name, provider object id) can go stale when a
+        # class is unloaded and redefined with a changed declaration, or
+        # when object ids are recycled. A validator that silently skips
+        # after a reload is worse than no validator, so correctness wins
+        # over an optimization with no observable benefit.
+        #
+        # @param klass [Class] the Parse::Object subclass.
+        # @param field [Symbol] the `:vector` property name.
+        # @param provider [Parse::Embeddings::Provider]
+        # @raise [BindingMismatch]
+        # @return [void]
+        def verify!(klass, field, provider)
+          declared = klass.vector_properties[field.to_sym]
+          return if declared.nil?
+
+          check!(klass, field, provider, declared)
+          nil
+        end
+
+        # Audit every declared binding whose provider is registered.
+        # Intended for boot or CI: it surfaces a drifted declaration
+        # before a single embedding is written, rather than on the
+        # first save that happens to touch it.
+        #
+        # @param classes [Array<Class>, nil] defaults to every
+        #   Parse::Object subclass carrying `:vector` properties.
+        # @param strict [Boolean] when true, an unregistered provider
+        #   is itself a failure; otherwise those bindings are skipped
+        #   (a provider may be registered later in boot).
+        # @return [Array<String>] human-readable problems, empty when clean.
+        def audit_all!(classes: nil, strict: false)
+          problems = []
+          begin
+            bindings = collect_bindings(classes)
+          rescue DiscoveryFailed => e
+            return [e.message]
+          end
+
+          bindings.each do |klass, field, declared|
+            provider_name = declared[:provider]
+            next if provider_name.nil?
+
+            begin
+              provider = Parse::Embeddings.provider(provider_name)
+            rescue Parse::Embeddings::ProviderNotRegistered => e
+              problems << "#{klass}##{field}: #{e.message}" if strict
+              next
+            end
+
+            begin
+              check!(klass, field, provider, declared)
+            rescue BindingMismatch => e
+              problems << e.message
+            end
+          end
+          problems
+        end
+
+        # {.audit_all!} that raises instead of returning problems.
+        #
+        # @raise [BindingMismatch] when any binding disagrees.
+        # @return [void]
+        def audit_all_or_raise!(classes: nil, strict: false)
+          problems = audit_all!(classes: classes, strict: strict)
+          return if problems.empty?
+
+          raise BindingMismatch,
+                "Parse::Embeddings binding audit failed:\n  - #{problems.join("\n  - ")}"
+        end
+
+        # Retained as a no-op for callers that invoked it when this
+        # module memoized verdicts.
+        # @return [void]
+        def reset!
+          nil
+        end
+
+        private
+
+        # Read a provider accessor, distinguishing "not implemented"
+        # from a legitimate nil. Returns `:unavailable` for the former
+        # so {#check!} can fail closed rather than skip the comparison.
+        def accessor(provider, method)
+          value = provider.public_send(method)
+          value.nil? ? :unavailable : value
+        rescue NotImplementedError, NoMethodError
+          :unavailable
+        end
+
+        def check!(klass, field, provider, declared)
+          declared_model = declared[:model]
+          if declared_model
+            actual_model = accessor(provider, :model_name)
+            # A declaration states a requirement. A provider that cannot
+            # answer what model it runs cannot satisfy it, so this fails
+            # closed — otherwise a custom provider without `model_name`
+            # would write same-width embeddings that are never checked
+            # against the declaration at all.
+            if actual_model == :unavailable
+              raise BindingMismatch,
+                    "#{klass}##{field} declares model: #{declared_model.inspect} but the " \
+                    "provider registered as #{declared[:provider].inspect} " \
+                    "(#{provider.class}) does not report a usable #model_name, so the " \
+                    "binding cannot be verified. Implement #model_name on the provider, " \
+                    "or drop `model:` from the property to opt out of the check."
+            end
+            if declared_model.to_s != actual_model.to_s
+              raise BindingMismatch,
+                    "#{klass}##{field} declares model: #{declared_model.inspect} but the " \
+                    "provider registered as #{declared[:provider].inspect} is running " \
+                    "#{actual_model.inspect}. Vectors from different models are not " \
+                    "comparable; embedding with the current provider would corrupt this " \
+                    "index. Update the declaration and re-embed, or register the declared " \
+                    "model."
+            end
+          end
+
+          declared_dims = declared[:dimensions]
+          if declared_dims
+            actual_dims = accessor(provider, :dimensions)
+            if actual_dims == :unavailable
+              raise BindingMismatch,
+                    "#{klass}##{field} declares dimensions: #{declared_dims} but the " \
+                    "provider registered as #{declared[:provider].inspect} " \
+                    "(#{provider.class}) does not report a usable #dimensions, so the " \
+                    "binding cannot be verified. #dimensions is required by the provider " \
+                    "protocol."
+            end
+            if declared_dims != actual_dims
+              raise BindingMismatch,
+                    "#{klass}##{field} declares dimensions: #{declared_dims} but the provider " \
+                    "registered as #{declared[:provider].inspect} emits #{actual_dims}-dim " \
+                    "vectors. Fix the declaration or configure the provider's width before " \
+                    "embedding."
+            end
+          end
+          nil
+        end
+
+        def collect_bindings(classes)
+          list = classes || default_classes
+          list.flat_map do |klass|
+            next [] unless klass.respond_to?(:vector_properties)
+            klass.vector_properties.map { |field, declared| [klass, field, declared] }
+          end
+        end
+
+        # Discovery must NOT swallow its own failure: an empty list from
+        # a crashed sweep is indistinguishable from a clean audit, so
+        # `audit_all_or_raise!` would report success having checked
+        # nothing. Failures propagate as {DiscoveryFailed} and
+        # {.audit_all!} converts them into a reported problem.
+        def default_classes
+          return [] unless defined?(Parse::Object)
+          ObjectSpace.each_object(Class).select do |k|
+            k < Parse::Object && k.respond_to?(:vector_properties) &&
+              !k.vector_properties.empty?
+          end
+        rescue StandardError => e
+          raise DiscoveryFailed,
+                "Parse::Embeddings::BindingAudit could not enumerate Parse::Object " \
+                "subclasses (#{e.class}: #{e.message}); the audit checked nothing. " \
+                "Pass `classes:` explicitly to audit a known set."
+        end
+      end
+    end
+  end
+end

data/lib/parse/embeddings/media_file.rb

@@ -0,0 +1,136 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module Embeddings
+    # A file-backed image or video input that is **streamed** into the
+    # request body rather than read into memory.
+    #
+    # This is the memory-safe counterpart to
+    # {ImageFetch::FetchedImage}, which holds raw bytes. A MediaFile
+    # holds only a path, a sniffed MIME type, and a byte count; the
+    # bytes are read and base64-encoded incrementally by
+    # {StreamingBody} while the request is being written to the socket.
+    # Peak memory stays at {StreamingBody::READ_CHUNK} no matter how
+    # large the file is, which is what makes video viable on a small
+    # dyno.
+    #
+    # Only the first 16 bytes are read at construction time, to sniff
+    # the container. The `Content-Type` header and the filename
+    # extension are never consulted.
+    #
+    # @example stream a local image
+    #   img = Parse::Embeddings::MediaFile.image("diagram.png")
+    #   provider.embed_image([img])
+    #
+    # @example stream a local video
+    #   clip = Parse::Embeddings::MediaFile.video("demo.mp4")
+    #   provider.embed_video([clip])
+    class MediaFile
+      # Voyage documents 20 MB per image and 20 MB per video.
+      # Overridable via {Parse::Embeddings.max_media_bytes=}.
+      DEFAULT_MAX_MEDIA_BYTES = 20 * 1024 * 1024
+
+      # Raised when a file exceeds {Parse::Embeddings.max_media_bytes}.
+      class TooLarge < Parse::Embeddings::Error; end
+
+      # @return [String] absolute path to the backing file.
+      attr_reader :path
+      # @return [String] sniffed MIME type.
+      attr_reader :mime_type
+      # @return [Integer] size in bytes, captured at construction.
+      attr_reader :byte_size
+      # @return [Symbol] `:image` or `:video`.
+      attr_reader :kind
+
+      class << self
+        # Wrap a local image file. Verifies the magic bytes against
+        # {Parse::Embeddings.allowed_image_types}.
+        #
+        # @param path [String]
+        # @return [MediaFile]
+        # @raise [ImageFetch::InvalidImageType]
+        def image(path)
+          header = read_header(path)
+          mime = ImageFetch.sniff_mime(header)
+          if mime.nil?
+            raise ImageFetch::InvalidImageType.new(:unknown_magic,
+              "Parse::Embeddings::MediaFile.image: #{path} matches no supported image " \
+              "format (JPEG/PNG/GIF/WebP).")
+          end
+          allowed = Parse::Embeddings.allowed_image_types
+          unless allowed.include?(mime)
+            raise ImageFetch::InvalidImageType.new(:type_not_allowed,
+              "Parse::Embeddings::MediaFile.image: sniffed type #{mime.inspect} is not in " \
+              "Parse::Embeddings.allowed_image_types (#{allowed.inspect}).")
+          end
+          new(path: path, mime_type: mime, kind: :image)
+        end
+
+        # Wrap a local video file. Verifies the magic bytes against
+        # {Parse::Embeddings.allowed_video_types}.
+        #
+        # @param path [String]
+        # @return [MediaFile]
+        # @raise [VideoSource::InvalidVideoType]
+        def video(path)
+          header = read_header(path)
+          new(path: path, mime_type: VideoSource.verify!(header), kind: :video)
+        end
+
+        private
+
+        # Read only enough bytes to sniff a container. Deliberately
+        # tiny — the whole point of this class is to never hold the
+        # file. A file shorter than this is passed through as-is so the
+        # sniffers can reject it with their own error.
+        def read_header(path)
+          unless ::File.file?(path)
+            raise ArgumentError,
+                  "Parse::Embeddings::MediaFile: #{path.inspect} is not a readable file."
+          end
+          ::File.open(path, "rb") { |f| f.read(16).to_s }
+        end
+      end
+
+      def initialize(path:, mime_type:, kind:)
+        @path = ::File.expand_path(path)
+        @mime_type = mime_type
+        @kind = kind
+        @byte_size = ::File.size(@path)
+        if @byte_size.zero?
+          raise ArgumentError,
+                "Parse::Embeddings::MediaFile: #{path.inspect} is empty."
+        end
+        cap = Parse::Embeddings.max_media_bytes
+        if @byte_size > cap
+          raise TooLarge,
+                "Parse::Embeddings::MediaFile: #{path.inspect} is #{@byte_size} bytes, over " \
+                "the #{cap}-byte limit (Parse::Embeddings.max_media_bytes). Voyage rejects " \
+                "media above 20 MB — downscale or re-encode before embedding."
+        end
+      end
+
+      # The `data:` URI prefix that precedes the streamed base64 in the
+      # wire body. The payload itself is never concatenated here.
+      #
+      # @return [String]
+      def data_uri_prefix
+        "data:#{mime_type};base64,"
+      end
+
+      # Segment descriptor consumed by {StreamingBody}.
+      #
+      # @return [Hash]
+      def stream_segment
+        { path: @path, size: @byte_size }
+      end
+
+      def inspect
+        "#<Parse::Embeddings::MediaFile kind=#{@kind} mime_type=#{@mime_type.inspect} " \
+        "bytes=#{@byte_size} path=#{@path.inspect}>"
+      end
+      alias_method :to_s, :inspect
+    end
+  end
+end

data/lib/parse/embeddings/provider.rb

@@ -24,6 +24,7 @@ module Parse
     # Subclasses MAY override:
     #
     # * {#embed_image}      — v5.1 (multimodal); default `NotImplementedError`
+    # * {#embed_video}      — v5.6 (multimodal); default `NotImplementedError`
     # * {#embed_batch_size} — provider-recommended batch size hint
     # * {#max_input_tokens} — chunker hint
     # * {#normalize?}       — whether output is unit-normalized
@@ -76,6 +77,44 @@ module Parse
         raise NotImplementedError, "#{self.class} does not support image embedding"
       end
 
+      # Embed video sources. Same contract and default posture as
+      # {#embed_image}: providers that do not offer video leave this
+      # raising, and callers discover support through {#modalities}
+      # rather than by rescuing.
+      #
+      # Video payloads are large enough that holding one in memory is a
+      # real operational risk, so the two source forms concrete
+      # providers should accept are:
+      #
+      # * a URL String, forwarded for provider-side fetch after
+      #   {Parse::Embeddings.validate_image_url!} screens it (the SDK
+      #   never downloads the video), and
+      # * a {Parse::Embeddings::MediaFile}, streamed into the request
+      #   body by {Parse::Embeddings::StreamingBody} without ever being
+      #   fully resident.
+      #
+      # Concrete overrides must accept `allow_insecure:` explicitly or
+      # absorb it via `**opts` — see {#embed_image} for why.
+      #
+      # @param sources [Array<String, Parse::Embeddings::MediaFile>]
+      # @param input_type [Symbol] `:search_query` or `:search_document`.
+      # @param allow_insecure [Boolean] forwarded to the URL validator.
+      # @param opts [Hash] provider-specific options.
+      # @return [Array<Array<Float>>] vectors aligned 1:1 with `sources`.
+      # @raise [NotImplementedError] unless the provider offers video.
+      def embed_video(sources, input_type: :search_document, allow_insecure: false, **opts)
+        raise NotImplementedError, "#{self.class} does not support video embedding"
+      end
+
+      # @return [Boolean] whether this provider accepts `modality`.
+      #   Prefer this over rescuing {NotImplementedError} — it answers
+      #   the question without issuing a call.
+      #
+      # @param modality [Symbol] one of `:text`, `:image`, `:video`.
+      def supports_modality?(modality)
+        modalities.include?(modality.to_sym)
+      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