chore: import upstream snapshot with attribution

docs-website/reference_versioned_docs/version-2.18/integrations-api/twelvelabs.md

@@ -0,0 +1,347 @@
+---
+title: "TwelveLabs"
+id: integrations-twelvelabs
+description: "TwelveLabs integration for Haystack"
+slug: "/integrations-twelvelabs"
+---
+
+
+## haystack_integrations.components.converters.twelvelabs.video_converter
+
+### TwelveLabsVideoConverter
+
+Converts videos to Haystack Documents using TwelveLabs Pegasus.
+
+Pegasus is a video-language model that analyzes a video on the fly (its
+visuals **and** its own audio ASR) and returns text. Each source video
+becomes one Document whose content is Pegasus's analysis (e.g. a description
+plus a transcript) — no frame extraction or separate transcription step.
+
+Sources may be publicly accessible direct video URLs or local file paths
+(uploaded to TwelveLabs, up to 200 MB).
+
+### Usage example
+
+```python
+from haystack_integrations.components.converters.twelvelabs import TwelveLabsVideoConverter
+
+# Set the TWELVELABS_API_KEY environment variable
+converter = TwelveLabsVideoConverter()
+result = converter.run(sources=["https://example.com/clip.mp4"])
+print(result["documents"][0].content)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("TWELVELABS_API_KEY"),
+    model: str = DEFAULT_MODEL,
+    prompt: str = DEFAULT_PROMPT,
+    temperature: float = 0.2,
+    max_tokens: int = 16384
+) -> None
+```
+
+Create a TwelveLabsVideoConverter.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The TwelveLabs API key. Read from the `TWELVELABS_API_KEY`
+  environment variable by default.
+- **model** (<code>str</code>) – The Pegasus model name (`pegasus1.5` or `pegasus1.2`).
+- **prompt** (<code>str</code>) – The analysis prompt sent to Pegasus for each video.
+- **temperature** (<code>float</code>) – Sampling temperature (0-1).
+- **max_tokens** (<code>int</code>) – Maximum output tokens per analysis.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TwelveLabsVideoConverter
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>TwelveLabsVideoConverter</code> – Deserialized component.
+
+#### run
+
+```python
+run(
+    sources: list[str],
+    meta: dict[str, Any] | list[dict[str, Any]] | None = None,
+) -> dict[str, list[Document]]
+```
+
+Convert videos to Documents with Pegasus.
+
+**Parameters:**
+
+- **sources** (<code>list\[str\]</code>) – Video sources — publicly accessible direct video URLs or
+  local file paths.
+- **meta** (<code>dict\[str, Any\] | list\[dict\[str, Any\]\] | None</code>) – Optional metadata to attach to the produced Documents. Either
+  a single dict applied to all, or a list aligned with `sources`.
+
+**Returns:**
+
+- <code>dict\[str, list\[Document\]\]</code> – A dictionary with key `documents`: the produced Documents.
+
+## haystack_integrations.components.embedders.twelvelabs.document_embedder
+
+### TwelveLabsDocumentEmbedder
+
+Embeds the text content of Documents using TwelveLabs Marengo.
+
+Computes a Marengo embedding for each Document's `content` and stores it on
+`Document.embedding`. Because Marengo embeds text, images, audio, and video
+into one shared space, these embeddings support cross-modal retrieval.
+
+### Usage example
+
+```python
+from haystack import Document
+from haystack_integrations.components.embedders.twelvelabs import TwelveLabsDocumentEmbedder
+
+# Set the TWELVELABS_API_KEY environment variable
+doc_embedder = TwelveLabsDocumentEmbedder()
+docs = [Document(content="a cat playing piano")]
+docs = doc_embedder.run(documents=docs)["documents"]
+print(docs[0].embedding)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("TWELVELABS_API_KEY"),
+    model: str = DEFAULT_MODEL,
+    prefix: str = "",
+    suffix: str = "",
+    batch_size: int = 32,
+    progress_bar: bool = True,
+    meta_fields_to_embed: list[str] | None = None,
+    embedding_separator: str = "\n"
+) -> None
+```
+
+Create a TwelveLabsDocumentEmbedder.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The TwelveLabs API key. Read from the `TWELVELABS_API_KEY`
+  environment variable by default.
+- **model** (<code>str</code>) – The Marengo model name.
+- **prefix** (<code>str</code>) – A string to add to the beginning of each text before embedding.
+- **suffix** (<code>str</code>) – A string to add to the end of each text before embedding.
+- **batch_size** (<code>int</code>) – Number of Documents per batch; within a batch `run_async` embeds concurrently.
+- **progress_bar** (<code>bool</code>) – Whether to show a progress bar while embedding. Can be helpful
+  to disable in production deployments to keep the logs clean.
+- **meta_fields_to_embed** (<code>list\[str\] | None</code>) – List of meta fields that should be embedded along with the Document text.
+- **embedding_separator** (<code>str</code>) – Separator used to concatenate the meta fields to the Document text.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TwelveLabsDocumentEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>TwelveLabsDocumentEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(documents: list[Document]) -> dict[str, Any]
+```
+
+Embed a list of Documents.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The Documents to embed (their `content` is embedded).
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with keys:
+- `documents`: New Documents that are copies of the inputs with `embedding` populated.
+- `meta`: Metadata about the request (the model used).
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a list of Documents.
+
+#### run_async
+
+```python
+run_async(documents: list[Document]) -> dict[str, Any]
+```
+
+Asynchronously embed a list of Documents.
+
+Documents within each batch of `batch_size` are embedded concurrently.
+
+**Parameters:**
+
+- **documents** (<code>list\[Document\]</code>) – The Documents to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with keys `documents` (copies with `embedding` populated) and `meta`.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a list of Documents.
+
+## haystack_integrations.components.embedders.twelvelabs.text_embedder
+
+### TwelveLabsTextEmbedder
+
+Embeds strings using TwelveLabs Marengo.
+
+Marengo embeds text, images, audio, and video into a single shared vector
+space, so embeddings from this component are directly comparable (cosine
+similarity) with image/video embeddings from the same model — enabling
+cross-modal retrieval. Use it to embed a query before searching a document
+store populated with Marengo embeddings.
+
+### Usage example
+
+```python
+from haystack_integrations.components.embedders.twelvelabs import TwelveLabsTextEmbedder
+
+# Set the TWELVELABS_API_KEY environment variable
+text_embedder = TwelveLabsTextEmbedder()
+result = text_embedder.run(text="a cat playing piano")
+print(result["embedding"])
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    api_key: Secret = Secret.from_env_var("TWELVELABS_API_KEY"),
+    model: str = DEFAULT_MODEL,
+    prefix: str = "",
+    suffix: str = ""
+) -> None
+```
+
+Create a TwelveLabsTextEmbedder.
+
+**Parameters:**
+
+- **api_key** (<code>Secret</code>) – The TwelveLabs API key. Read from the `TWELVELABS_API_KEY`
+  environment variable by default.
+- **model** (<code>str</code>) – The Marengo model name.
+- **prefix** (<code>str</code>) – A string to add to the beginning of the text before embedding.
+- **suffix** (<code>str</code>) – A string to add to the end of the text before embedding.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> TwelveLabsTextEmbedder
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>TwelveLabsTextEmbedder</code> – Deserialized component.
+
+#### run
+
+```python
+run(text: str) -> dict[str, Any]
+```
+
+Embed a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The string to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with keys:
+- `embedding`: The embedding vector for the input string.
+- `meta`: Metadata about the request (the model used).
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.
+
+#### run_async
+
+```python
+run_async(text: str) -> dict[str, Any]
+```
+
+Asynchronously embed a single string.
+
+**Parameters:**
+
+- **text** (<code>str</code>) – The string to embed.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – A dictionary with keys `embedding` and `meta`.
+
+**Raises:**
+
+- <code>TypeError</code> – If the input is not a string.