@mastra/voyageai 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @mastra/voyageai
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- feat(voyageai): add VoyageAI embeddings and reranker integration ([#14296](https://github.com/mastra-ai/mastra/pull/14296))
+
+  Adds the `@mastra/voyageai` package under `embedders/` with:
+  - Text embeddings (voyage-4 and voyage-3 series, plus code/finance/law models)
+    with token-aware batching via the SDK `tokenize()` method
+  - Multimodal embeddings (text + images + video) via voyage-multimodal-3/3.5
+  - Contextualized chunk embeddings via voyage-context-3
+  - Rerankers (rerank-2.5 and rerank-2 families) implementing `RelevanceScoreProvider`

package/README.md

@@ -0,0 +1,365 @@
+# @mastra/voyageai
+
+VoyageAI embeddings integration for Mastra. Provides text, multimodal, and contextualized chunk embeddings using the official VoyageAI TypeScript SDK.
+
+## Installation
+
+```bash
+npm install @mastra/voyageai
+# or
+pnpm add @mastra/voyageai
+```
+
+## Configuration
+
+Set your VoyageAI API key:
+
+```bash
+export VOYAGE_API_KEY=your-api-key
+```
+
+Or pass it directly in the configuration.
+
+## Usage
+
+### Text Embeddings
+
+```typescript
+import { voyage, voyageEmbedding } from '@mastra/voyageai';
+
+// Use default model (voyage-3.5)
+const result = await voyage.doEmbed({ values: ['Hello world'] });
+console.log(result.embeddings); // [[0.1, 0.2, ...]]
+
+// Use specific model with options
+const model = voyageEmbedding({
+  model: 'voyage-3-large',
+  inputType: 'query',
+  outputDimension: 512,
+});
+const queryResult = await model.doEmbed({ values: ['search query'] });
+```
+
+### Pre-configured Models
+
+```typescript
+import { voyage } from '@mastra/voyageai';
+
+// Voyage-4 series (highest throughput)
+await voyage.v4large.doEmbed({ values: ['...'] }); // voyage-4-large (120k batch tokens)
+await voyage.v4.doEmbed({ values: ['...'] }); // voyage-4 (320k batch tokens)
+await voyage.v4lite.doEmbed({ values: ['...'] }); // voyage-4-lite (1M batch tokens)
+
+// Voyage-3 series
+await voyage.large.doEmbed({ values: ['...'] }); // voyage-3-large
+await voyage.v35.doEmbed({ values: ['...'] }); // voyage-3.5
+await voyage.v35lite.doEmbed({ values: ['...'] }); // voyage-3.5-lite
+await voyage.code.doEmbed({ values: ['...'] }); // voyage-code-3
+await voyage.finance.doEmbed({ values: ['...'] }); // voyage-finance-2
+await voyage.law.doEmbed({ values: ['...'] }); // voyage-law-2
+```
+
+### With Mastra Memory
+
+```typescript
+import { Memory } from '@mastra/memory';
+import { PgVector } from '@mastra/pg';
+import { voyage } from '@mastra/voyageai';
+
+const memory = new Memory({
+  vector: new PgVector(connectionString),
+  embedder: voyage,
+  options: {
+    semanticRecall: { topK: 5 },
+  },
+});
+```
+
+### VoyageAI-Specific Options
+
+```typescript
+import { voyageEmbedding } from '@mastra/voyageai';
+
+const model = voyageEmbedding({
+  model: 'voyage-3.5',
+  inputType: 'query', // 'query' | 'document' for retrieval optimization
+  outputDimension: 512, // 256 | 512 | 1024 | 2048
+  outputDtype: 'float', // 'float' | 'int8' | 'uint8' | 'binary' | 'ubinary'
+  truncation: true, // Handle long inputs
+});
+```
+
+### Runtime Options Override
+
+```typescript
+const result = await model.doEmbed({
+  values: ['query text'],
+  providerOptions: {
+    voyage: {
+      inputType: 'query',
+      outputDimension: 256,
+    },
+  },
+});
+```
+
+## Multimodal Embeddings
+
+Embed interleaved text + images + video (3.5 only):
+
+```typescript
+import { voyageMultimodalEmbedding } from '@mastra/voyageai';
+
+const multimodal = voyageMultimodalEmbedding('voyage-multimodal-3.5');
+
+const result = await multimodal.doEmbed({
+  values: [
+    {
+      content: [
+        { type: 'text', text: 'A photo of a cat' },
+        { type: 'image_url', image_url: 'https://example.com/cat.jpg' },
+        // video_url supported on voyage-multimodal-3.5
+      ],
+    },
+  ],
+});
+
+// Use with vector store directly
+await vectorStore.upsert({
+  vectors: result.embeddings,
+  metadata: [{ description: 'cat photo' }],
+});
+```
+
+### Content Types
+
+- `{ type: 'text', text: string }` - Text content
+- `{ type: 'image_url', image_url: string }` - Image from URL
+- `{ type: 'image_base64', image_base64: string }` - Base64-encoded image
+- `{ type: 'video_url', video_url: string }` - Video from URL (3.5 only)
+
+## Contextualized Chunk Embeddings
+
+Embed chunks with document context to avoid "context loss":
+
+```typescript
+import { voyageContextualizedEmbedding } from '@mastra/voyageai';
+
+const contextual = voyageContextualizedEmbedding('voyage-context-3');
+
+// Embed document chunks (inner arrays = chunks from same document)
+const result = await contextual.doEmbed({
+  values: [['Paragraph 1 from doc 1...', 'Paragraph 2 from doc 1...'], ['Content from doc 2...']],
+  inputType: 'document',
+});
+
+// Returns embeddings for each chunk, preserving document context
+console.log(result.embeddings.length); // 3 (2 from doc 1, 1 from doc 2)
+console.log(result.chunkCounts); // [2, 1]
+
+// Query embedding
+const queryEmbedding = await contextual.embedQuery('What was the revenue?');
+```
+
+### Helper Methods
+
+```typescript
+// Embed a query
+const queryEmbedding = await contextual.embedQuery('search query');
+
+// Embed chunks from a single document
+const docEmbeddings = await contextual.embedDocumentChunks(['First paragraph...', 'Second paragraph...']);
+
+// Get embeddings grouped by document
+const grouped = await contextual.doEmbedGrouped({
+  values: [['chunk1', 'chunk2'], ['chunk3']],
+  inputType: 'document',
+});
+console.log(grouped.embeddingsByDocument); // [[[...], [...]], [[...]]]
+```
+
+## Available Models
+
+### Text Embedding Models
+
+| Model              | Use Case                                | Dimensions        | Batch Tokens |
+| ------------------ | --------------------------------------- | ----------------- | ------------ |
+| `voyage-4-large`   | Best quality, highest batch capacity    | 256/512/1024/2048 | 120k         |
+| `voyage-4`         | Balanced quality/speed, high throughput | 256/512/1024/2048 | 320k         |
+| `voyage-4-lite`    | Maximum throughput                      | 256/512/1024/2048 | 1M           |
+| `voyage-3-large`   | Best quality, multilingual              | 256/512/1024/2048 | 120k         |
+| `voyage-3.5`       | Balanced quality/speed                  | 256/512/1024/2048 | 320k         |
+| `voyage-3.5-lite`  | Lowest latency/cost                     | 256/512/1024/2048 | 1M           |
+| `voyage-code-3`    | Code retrieval                          | 256/512/1024/2048 | 32k          |
+| `voyage-finance-2` | Finance domain                          | 1024              | 32k          |
+| `voyage-law-2`     | Legal domain                            | 1024              | 32k          |
+
+### Multimodal Models
+
+| Model                   | Capabilities          |
+| ----------------------- | --------------------- |
+| `voyage-multimodal-3`   | Text + images         |
+| `voyage-multimodal-3.5` | Text + images + video |
+
+### Contextualized Models
+
+| Model              | Use Case                     |
+| ------------------ | ---------------------------- |
+| `voyage-context-3` | Chunks with document context |
+
+### Reranker Models
+
+| Model             | Context Length | Description                             |
+| ----------------- | -------------- | --------------------------------------- |
+| `rerank-2.5`      | 32000          | Best quality with instruction-following |
+| `rerank-2.5-lite` | 32000          | Optimized for latency and quality       |
+| `rerank-2`        | 16000          | Second-gen with multilingual support    |
+| `rerank-2-lite`   | 8000           | Second-gen, latency-optimized           |
+| `rerank-1`        | 8000           | First-gen, quality-focused              |
+| `rerank-lite-1`   | 4000           | First-gen, latency-optimized            |
+
+## Reranking
+
+VoyageAI rerankers implement the `RelevanceScoreProvider` interface for use with Mastra's reranking system.
+
+### Basic Usage
+
+```typescript
+import { voyage, voyageReranker, createVoyageReranker } from '@mastra/voyageai';
+
+// Use pre-configured reranker (rerank-2.5)
+const defaultReranker = voyage.reranker;
+
+// Or create with specific model
+const liteReranker = createVoyageReranker('rerank-2.5-lite');
+
+// Or with full config
+const customReranker = createVoyageReranker({
+  model: 'rerank-2.5',
+  truncation: true,
+});
+```
+
+### Get Relevance Score
+
+```typescript
+// Score a single document against a query
+const score = await reranker.getRelevanceScore(
+  'What is machine learning?',
+  'Machine learning is a subset of artificial intelligence...',
+);
+console.log(score); // 0.85
+```
+
+### Rerank Multiple Documents
+
+```typescript
+// Rerank multiple documents efficiently in one API call
+const results = await reranker.rerankDocuments(
+  'What is the capital of France?',
+  ['Paris is the capital of France.', 'London is the capital of England.', 'Berlin is the capital of Germany.'],
+  2, // topK - optional
+);
+
+// Results sorted by relevance
+console.log(results);
+// [
+//   { document: 'Paris is the capital of France.', index: 0, score: 0.95 },
+//   { document: 'Berlin is the capital of Germany.', index: 2, score: 0.32 },
+// ]
+```
+
+### With Mastra RAG
+
+```typescript
+import { createVectorQueryTool } from '@mastra/rag';
+import { voyage } from '@mastra/voyageai';
+
+const tool = createVectorQueryTool({
+  vectorStore,
+  model: voyage, // Embedder
+  reranker: {
+    model: voyage.reranker, // VoyageAI reranker
+    options: { topK: 5 },
+  },
+});
+```
+
+### Pre-configured Reranker Models
+
+```typescript
+import { voyage } from '@mastra/voyageai';
+
+// Default reranker (rerank-2.5)
+voyage.reranker;
+
+// Specific models
+voyage.reranker25; // rerank-2.5
+voyage.reranker25lite; // rerank-2.5-lite
+voyage.reranker2; // rerank-2
+voyage.reranker2lite; // rerank-2-lite
+
+// Create custom
+voyage.createReranker({ model: 'rerank-1', truncation: false });
+```
+
+## AI SDK Compatibility
+
+The package exports models compatible with both AI SDK v5 (V2) and v6 (V3):
+
+```typescript
+// V3 (default, AI SDK v6)
+const v3Model = voyageEmbedding('voyage-3.5');
+v3Model.specificationVersion; // 'v3'
+
+// V2 (AI SDK v5)
+const v2Model = voyageEmbeddingV2('voyage-3.5');
+v2Model.specificationVersion; // 'v2'
+
+// Pre-configured V2 models
+voyage.largeV2; // voyage-3-large with V2 interface
+voyage.v35V2; // voyage-3.5 with V2 interface
+```
+
+## API Reference
+
+### Types
+
+```typescript
+type VoyageTextModel =
+  | 'voyage-4-large'
+  | 'voyage-4'
+  | 'voyage-4-lite'
+  | 'voyage-3-large'
+  | 'voyage-3.5'
+  | 'voyage-3.5-lite'
+  | 'voyage-code-3'
+  | 'voyage-finance-2'
+  | 'voyage-law-2';
+
+type VoyageMultimodalModel = 'voyage-multimodal-3' | 'voyage-multimodal-3.5';
+
+type VoyageContextModel = 'voyage-context-3';
+
+type VoyageInputType = 'query' | 'document' | null;
+type VoyageOutputDimension = 256 | 512 | 1024 | 2048;
+type VoyageOutputDtype = 'float' | 'int8' | 'uint8' | 'binary' | 'ubinary';
+
+type VoyageRerankerModel =
+  | 'rerank-2.5'
+  | 'rerank-2.5-lite'
+  | 'rerank-2'
+  | 'rerank-2-lite'
+  | 'rerank-1'
+  | 'rerank-lite-1';
+
+interface VoyageRerankerConfig {
+  model: VoyageRerankerModel;
+  apiKey?: string;
+  truncation?: boolean;
+}
+```
+
+## License
+
+Apache-2.0

package/dist/contextualized-embedding.d.ts

@@ -0,0 +1,137 @@
+/**
+ * VoyageAI Contextualized Chunk Embedding Model
+ *
+ * Embeds text chunks with document context, addressing the "context loss" problem
+ * that occurs when documents are split into individual chunks.
+ *
+ * Each chunk receives an embedding that reflects both its independent meaning
+ * AND its position within the broader document context.
+ */
+import type { VoyageContextModel, VoyageContextualizedEmbeddingConfig, VoyageProviderOptions, VoyageInputType, VoyageOutputDimension, VoyageOutputDtype } from './types.js';
+/**
+ * VoyageAI Contextualized Chunk Embedding Model
+ *
+ * Note: This does NOT implement EmbeddingModelV2<string> because contextualized
+ * inputs have a different structure (string[][] vs string[]).
+ *
+ * Input format: Nested lists where each inner list contains related chunks
+ * from the same document. Example:
+ * ```
+ * [
+ *   ['chunk1_from_doc1', 'chunk2_from_doc1'],  // Document 1 chunks
+ *   ['chunk1_from_doc2', 'chunk2_from_doc2'],  // Document 2 chunks
+ * ]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const model = new VoyageContextualizedEmbeddingModel({ model: 'voyage-context-3' });
+ *
+ * // Embed document chunks with context
+ * const docResult = await model.doEmbed({
+ *   values: [
+ *     ['Leafy Inc Q2 2024...', 'Revenue grew 15%...'],
+ *     ['Acme Corp announced...', 'The merger will...']
+ *   ],
+ *   inputType: 'document',
+ * });
+ *
+ * // Embed a query (single item per inner list)
+ * const queryResult = await model.doEmbed({
+ *   values: [['What was Leafy Inc revenue growth?']],
+ *   inputType: 'query',
+ * });
+ * ```
+ */
+export declare class VoyageContextualizedEmbeddingModel {
+    readonly provider: "voyage";
+    readonly modelId: string;
+    readonly maxEmbeddingsPerCall = 1000;
+    readonly maxTotalChunks = 16000;
+    readonly supportsParallelCalls = true;
+    private client;
+    private config;
+    constructor(config: VoyageContextualizedEmbeddingConfig);
+    /**
+     * Generate contextualized embeddings for grouped chunks
+     *
+     * @param args.values - Nested array where each inner array contains chunks from the same document
+     * @param args.inputType - 'query' for search queries, 'document' for content being indexed
+     * @param args.outputDimension - Output embedding dimension (256, 512, 1024, or 2048)
+     * @param args.outputDtype - Output data type
+     * @param args.providerOptions - Runtime options to override config
+     * @returns Object containing flattened embeddings array (one per chunk across all documents)
+     */
+    doEmbed(args: {
+        values: string[][];
+        inputType?: VoyageInputType;
+        outputDimension?: VoyageOutputDimension;
+        outputDtype?: VoyageOutputDtype;
+        abortSignal?: AbortSignal;
+        headers?: Record<string, string>;
+        providerOptions?: VoyageProviderOptions;
+    }): Promise<{
+        embeddings: number[][];
+        chunkCounts: number[];
+    }>;
+    /**
+     * Generate contextualized embeddings and return grouped by document
+     *
+     * @param args - Same as doEmbed
+     * @returns Embeddings grouped by document
+     */
+    doEmbedGrouped(args: {
+        values: string[][];
+        inputType?: VoyageInputType;
+        outputDimension?: VoyageOutputDimension;
+        outputDtype?: VoyageOutputDtype;
+        abortSignal?: AbortSignal;
+        headers?: Record<string, string>;
+        providerOptions?: VoyageProviderOptions;
+    }): Promise<{
+        embeddingsByDocument: number[][][];
+    }>;
+    /**
+     * Generate a query embedding (contextualized with itself)
+     *
+     * @param query - The search query text
+     * @returns Single embedding vector
+     */
+    embedQuery(query: string): Promise<number[]>;
+    /**
+     * Generate document chunk embeddings with context
+     *
+     * @param chunks - Array of text chunks from the same document
+     * @returns Array of embeddings, one per chunk
+     */
+    embedDocumentChunks(chunks: string[]): Promise<number[][]>;
+}
+/**
+ * Create a VoyageAI contextualized chunk embedding model
+ *
+ * @param config - Model configuration or model name string
+ * @returns VoyageContextualizedEmbeddingModel instance
+ *
+ * @example
+ * ```typescript
+ * // With model name only
+ * const model = createVoyageContextualizedEmbedding('voyage-context-3');
+ *
+ * // With full config
+ * const model = createVoyageContextualizedEmbedding({
+ *   model: 'voyage-context-3',
+ *   outputDimension: 512,
+ * });
+ *
+ * // Embed document chunks with context
+ * const result = await model.doEmbed({
+ *   values: [
+ *     ['First paragraph of doc 1...', 'Second paragraph...'],
+ *     ['Content from doc 2...']
+ *   ],
+ *   inputType: 'document',
+ * });
+ * ```
+ */
+export declare function createVoyageContextualizedEmbedding(config: VoyageContextualizedEmbeddingConfig | VoyageContextModel): VoyageContextualizedEmbeddingModel;
+//# sourceMappingURL=contextualized-embedding.d.ts.map

package/dist/contextualized-embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextualized-embedding.d.ts","sourceRoot":"","sources":["../src/contextualized-embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EACV,kBAAkB,EAClB,mCAAmC,EACnC,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAUjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,kCAAkC;IAC7C,QAAQ,CAAC,QAAQ,EAAG,QAAQ,CAAU;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,oBAAoB,QAAQ;IACrC,QAAQ,CAAC,cAAc,SAAS;IAChC,QAAQ,CAAC,qBAAqB,QAAQ;IAEtC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAsC;gBAExC,MAAM,EAAE,mCAAmC;IAcvD;;;;;;;;;OASG;IACG,OAAO,CAAC,IAAI,EAAE;QAClB,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;QAC5B,eAAe,CAAC,EAAE,qBAAqB,CAAC;QACxC,WAAW,CAAC,EAAE,iBAAiB,CAAC;QAChC,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,eAAe,CAAC,EAAE,qBAAqB,CAAC;KACzC,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAsC9D;;;;;OAKG;IACG,cAAc,CAAC,IAAI,EAAE;QACzB,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;QAC5B,eAAe,CAAC,EAAE,qBAAqB,CAAC;QACxC,WAAW,CAAC,EAAE,iBAAiB,CAAC;QAChC,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,eAAe,CAAC,EAAE,qBAAqB,CAAC;KACzC,GAAG,OAAO,CAAC;QAAE,oBAAoB,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;KAAE,CAAC;IA2BnD;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQlD;;;;;OAKG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CAOjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,mCAAmC,GAAG,kBAAkB,GAC/D,kCAAkC,CAGpC"}