Description
Voyage Text Embeddings provides a BYOK adapter for turning text into vectors used by semantic search and knowledge storage. VoyageAdapter implements the shared EmbeddingProvider contract for single and batch requests, reports the model, dimensions, provider, token usage, and truncation state, and exposes cost estimation for the configured model. Credentials and endpoint settings arrive through constructor configuration rather than environment reads inside the package.
The adapter supports Voyage's asymmetric retrieval mode: callers can mark stored content as document and queries as query, sending the provider's input_type on the wire. Oversized text is truncated at a word boundary and flagged instead of being rejected. Batch output is restored to input order, dimensions are validated, and typed authentication, rate-limit, batch, and availability errors preserve actionable failure distinctions.
Selling Points
- Query/document input modes improve retrieval quality when the same matched mode pair is used for indexing and search.
- One adapter handles both individual and batch embedding while preserving input order and usage accounting.
- Word-boundary truncation keeps long content moving through pipelines and tells callers which results need chunking.
- BYOK construction keeps API keys at the composition boundary and out of package-global state.
- Retry and error classification let consumers distinguish invalid credentials, provider throttling, and temporary unavailability.
User Story
A deployer supplies a Voyage API key at the composition root and constructs the adapter for Dotabase indexing and Universal Search. Stored rows are embedded with inputType: "document" and incoming search text with inputType: "query". The caller receives vectors plus usage and truncation metadata it can meter, cache, or use to schedule chunking.
Extension Surface
Pluggable is the first true rung because packages/embedding-providers/src/internal/types.ts defines the formal EmbeddingProvider implementation contract and packages/embedding-providers/src/provider-registry.ts exposes provider registration. VoyageAdapter in packages/embedding-providers/src/internal/voyage.ts is one swappable implementation; consumers depend on the contract rather than its class.
Capabilities & Limits
- Embeds one text or batches up to 50 inputs and validates every returned 1,024-dimension vector.
- Supports optional query/document input typing, timeout, bounded retries, usage reporting, and exact-model cost estimation.
- Returns a
truncatedflag or truncated index list when text exceeds the model budget. - Limits: callers must use matching document/query modes; querying typed vectors against untyped stored vectors degrades relevance.
- Limits: this adapter is text-only and requires a caller-supplied Voyage key; multimodal inputs use a different provider capability.
Implementation Map
packages/embedding-providers/src/internal/voyage.tspackages/embedding-providers/src/internal/voyage-http.tspackages/embedding-providers/src/internal/types.tspackages/embedding-providers/src/internal/tokenize.tspackages/embedding-providers/src/internal/cost.ts