Hi! I'm Mohit, I work at TwelveLabs (@mohit-twelvelabs).

What this adds

A new opt-in helper, docarray.utils.twelvelabs.TwelveLabsEmbedder, that populates the embedding field of VideoDoc (and text queries) using TwelveLabs Marengo multimodal embeddings.

Marengo maps text and video into the same 512-dimensional vector space, so a text-query embedding can be compared directly against video embeddings. That makes it a natural fit for DocArray's find / document-index cross-modal search:

from docarray import DocList
from docarray.documents import VideoDoc
from docarray.utils.twelvelabs import TwelveLabsEmbedder

embedder = TwelveLabsEmbedder()  # reads TWELVELABS_API_KEY from the env

docs = DocList[VideoDoc]([VideoDoc(url="https://example.com/clip.mp4")])
embedder.embed_docs(docs)            # fills docs[*].embedding in place

q = embedder.embed_query("a dog catching a frisbee")  # same 512-d space

Why it helps this project

DocArray already models video as a first-class type (VideoDoc) and ships vector-search backends, but leaves embedding generation to the user. This wires up a production multimodal video embedder so users can go from VideoDoc to searchable vectors without leaving DocArray, and unlocks true cross-modal (text-to-video) retrieval.

Opt-in / non-breaking

• Nothing imports twelvelabs unless you use the helper; it's gated behind a new twelvelabs extra (pip install "docarray[twelvelabs]") using the same import_library pattern as the other optional integrations.
• No existing defaults or behavior change.

How it was tested

• No-network unit tests (fake client) cover text embedding, video-segment averaging, in-place embed_docs, the TextDoc query path, and the missing-URL / missing-key error cases — these run in CI without any credentials.
• Live tests gated on TWELVELABS_API_KEY (skipped when unset). I ran both locally against the real API with twelvelabs==1.2.8: the text-embedding test and the video-embedding test (Big Buck Bunny sample) both pass and return 512-d vectors.
• black -S, isort --profile black, and ruff are clean on the changed files.

You can grab a free API key at https://twelvelabs.io — there's a generous free tier.