[bot] Add Voyage AI Python SDK integration for embed and rerank execution instrumentation

[braintrust-bot]

Summary

The Voyage AI Python SDK (voyageai) is the official Python client for Voyage AI, a leading provider of state-of-the-art text embedding and reranking models widely used in production RAG pipelines. The SDK exposes Client.embed() for generating dense vector embeddings and Client.rerank() for relevance scoring between queries and documents. This repository has zero instrumentation for any Voyage AI SDK surface — no integration directory, no wrapper, no patcher, no auto_instrument() support.

Voyage AI's embedding models (voyage-3, voyage-3-large, voyage-code-3, voyage-finance-2, voyage-law-2, etc.) are used as standalone embedding and reranking layers in LLM applications. Users who call voyageai.Client.embed() or voyageai.Client.rerank() directly get no Braintrust spans.

The Voyage AI API has its own request/response format and cannot be wrapped via wrap_openai(). The SDK is actively maintained (v0.3.7, December 2025). Comparable provider SDKs with execution surfaces in this repo include cohere (which also provides embeddings and reranking), huggingface-hub (embeddings via feature_extraction() and sentence_similarity()).

What needs to be instrumented

The voyageai package exposes these execution surfaces via Client and AsyncClient, none of which are instrumented:

Embeddings (highest priority)

SDK Method	Description
Client.embed(texts, model, ...)	Generate embeddings for a list of texts
AsyncClient.embed(texts, model, ...)	Async embeddings
Client.multimodal_embed(inputs, model, ...)	Embeddings for mixed text + image inputs
AsyncClient.multimodal_embed(inputs, model, ...)	Async multimodal embeddings

Response shape: EmbeddingsObject with embeddings (list of lists of floats), total_tokens (prompt token count), and model. Token usage is directly available for span metrics.

Supported models include: voyage-3, voyage-3-large, voyage-3-lite, voyage-code-3, voyage-finance-2, voyage-law-2, voyage-multimodal-3.

Reranking

SDK Method	Description
Client.rerank(query, documents, model, ...)	Score relevance of documents against a query
AsyncClient.rerank(query, documents, model, ...)	Async reranking

Response shape: RerankingObject with results (list of RerankingResult with document, relevance_score, index), total_tokens, and model.

Implementation notes

Authentication: API key passed to voyageai.Client(api_key=...) or via VOYAGE_API_KEY environment variable. VCR cassettes need Authorization: Bearer header sanitization.

Embedding input types: embed() accepts input_type parameter ("query", "document") that controls how the model encodes the text. This should be captured in span metadata.

Token truncation: Client.embed() accepts a truncation parameter that controls whether inputs longer than the model's context length are silently truncated. Relevant for observability.

Parameters relevant for span metadata: model, input_type, truncation, output_dimension (for Matryoshka embeddings), output_dtype.

Embedding dimension info: The integration should record the embedding dimension (available via voyageai.get_embedding_size(model)) in span metadata.

Proposed span shape

embed()

Span field	Content
input	texts (list of strings)
output	embedding dimension count, number of embeddings
metadata	provider: "voyageai", model, input_type, output_dimension
metrics	prompt_tokens (from total_tokens)

rerank()

Span field	Content
input	query, documents
output	top-k results with scores
metadata	provider: "voyageai", model, top_k
metrics	prompt_tokens (from total_tokens)

No coverage in any instrumentation layer

• No integration directory (py/src/braintrust/integrations/voyageai/)
• No wrapper function (e.g. wrap_voyageai())
• No patcher in any existing integration
• No nox test session (test_voyageai)
• No version entry in py/src/braintrust/integrations/versioning.py
• No mention in py/src/braintrust/integrations/__init__.py

A grep for voyageai, voyage_ai, or voyage-ai across py/src/braintrust/ returns zero matches.

Braintrust docs status

not_found — Voyage AI is not listed on the Braintrust AI providers page or the tracing guide. There is no proxy path documented for Voyage AI (the Braintrust AI Proxy targets completion/chat endpoints, not embedding/reranking APIs).

Upstream references

• voyageai on PyPI: https://pypi.org/project/voyageai/ (v0.3.7, December 2025)
• voyageai on GitHub: https://github.com/voyage-ai/voyageai-python
• Voyage AI docs: https://docs.voyageai.com/docs/introduction
• Embeddings API reference: https://docs.voyageai.com/docs/embeddings
• Reranking API reference: https://docs.voyageai.com/docs/reranker
• Model list: https://docs.voyageai.com/docs/models

Local repo files inspected

• py/src/braintrust/integrations/ — no voyageai/ directory on main
• py/src/braintrust/wrappers/ — no Voyage AI wrapper
• py/noxfile.py — no test_voyageai session
• py/pyproject.toml [tool.braintrust.matrix] — no voyageai entry
• py/src/braintrust/integrations/__init__.py — Voyage AI not listed
• py/src/braintrust/integrations/versioning.py — no Voyage AI version matrix
• Full repo grep for voyageai, voyage_ai, voyage-ai — zero matches in SDK source