@mastra/rag 2.6.7-alpha.0 → 2.6.8-alpha.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-rag
 description: Documentation for @mastra/rag. Use when working with @mastra/rag APIs, configuration, or implementation.
 metadata:
   package: "@mastra/rag"
-  version: "2.6.7-alpha.0"
+  version: "2.6.8-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.6.7-alpha.0",
+  "version": "2.6.8-alpha.0",
   "package": "@mastra/rag",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-rag-chunk.md

@@ -47,7 +47,7 @@ The following parameters are available for all chunking strategies. Each strateg
 
 **maxSize** (`number`): Maximum size of each chunk. Some strategy configurations (markdown with headers, HTML with headers) ignore this parameter. (Default: `4000`)
 
-**overlap** (`number`): Number of characters/tokens that overlap between chunks. (Default: `50`)
+**overlap** (`number`): Number of characters/tokens that overlap between chunks. Defaults to 200 for most strategies; the 'sentence' strategy defaults to 0. (Default: `200`)
 
 **lengthFunction** (`(text: string) => number`): Function to calculate text length. Defaults to character count.
 
@@ -130,7 +130,7 @@ The options documented below are passed directly at the top level of the configu
 
 ### Character
 
-**separators** (`string[]`): Array of separators to try in order of preference. The strategy will attempt to split on the first separator, then fall back to subsequent ones.
+**separator** (`string`): Character or string to split text on. (Default: `'\n\n'`)
 
 **isSeparatorRegex** (`boolean`): Whether the separator is a regex pattern (Default: `false`)
 

package/dist/docs/references/reference-rag-chunking-and-embedding.md

@@ -40,7 +40,7 @@ const chunks = await doc.chunk({
   overlap: 50,
   separators: ['\n'],
   extract: {
-    metadata: true, // Optionally extract metadata
+    title: true, // Optionally extract a title for each chunk
   },
 })
 ```

package/dist/docs/references/reference-rag-database-config.md

@@ -13,6 +13,7 @@ export type DatabaseConfig = {
   pinecone?: PineconeConfig
   pgvector?: PgVectorConfig
   chroma?: ChromaConfig
+  mongodb?: MongoDBConfig
   turbopuffer?: TurbopufferConfig
   [key: string]: any // Extensible for future databases
 }
@@ -64,9 +65,9 @@ Configuration options specific to PostgreSQL with pgvector extension.
 
 Configuration options specific to Chroma vector store.
 
-**where** (`Record<string, any>`): Metadata filtering conditions using MongoDB-style query syntax. Filters results based on metadata fields.
+**where** (`Where`): Metadata filtering conditions. Each field maps to a literal value or an operator expression ($gt, $gte, $lt, $lte, $ne, $eq, $in, $nin). Combine conditions with $and and $or.
 
-**whereDocument** (`Record<string, any>`): Document content filtering conditions. Allows filtering based on the actual document text content.
+**whereDocument** (`WhereDocument`): Document content filtering conditions using $contains and $not\_contains. Combine conditions with $and and $or.
 
 **Filter Syntax Examples:**
 
@@ -93,6 +94,17 @@ whereDocument: { "$contains": "API documentation" }
 - Content-based document filtering
 - Complex query combinations
 
+### `MongoDBConfig`
+
+Configuration options specific to MongoDB Atlas Vector Search.
+
+**numCandidates** (`number`): Number of candidates the HNSW graph considers before selecting the top-K results. Higher values improve recall at the cost of query latency. Must be greater than or equal to topK. Defaults to 20 × topK, capped at 10,000.
+
+**Use Cases:**
+
+- Improving recall for large collections
+- Lowering latency when approximate results are acceptable
+
 ### `TurbopufferConfig`
 
 Configuration options specific to Turbopuffer vector store.

package/dist/docs/references/reference-rag-document.md

@@ -10,7 +10,7 @@ The MDocument class processes documents for RAG applications. The main methods a
 
 **docs** (`Array<{ text: string, metadata?: Record<string, any> }>`): Array of document chunks with their text content and optional metadata
 
-**type** (`'text' | 'html' | 'markdown' | 'json' | 'latex'`): Type of document content
+**type** (`string`): Type of document content. Recognized values are 'text', 'html', 'markdown', 'json', and 'latex'.
 
 ## Static methods
 
@@ -53,9 +53,14 @@ static fromJSON(json: string, metadata?: Record<string, any>): MDocument
 Splits document into chunks and optionally extracts metadata.
 
 ```typescript
-async chunk(params?: ChunkParams): Promise<Chunk[]>
+async chunk(
+  params?: ChunkParams,
+  options?: { observabilityContext?: ObservabilityContext },
+): Promise<Chunk[]>
 ```
 
+Pass `observabilityContext` to attach the chunking and metadata extraction spans to an existing trace.
+
 See [chunk() reference](https://mastra.ai/reference/rag/chunk) for detailed options.
 
 ### `getDocs()`

package/dist/docs/references/reference-rag-extract-params.md

@@ -46,7 +46,7 @@ The `extract` parameter accepts the following fields:
 
 ### `TitleExtractorsArgs`
 
-**llm** (`MastraLanguageModel`): AI SDK language model to use for title extraction
+**llm** (`MastraLanguageModel | MastraLegacyLanguageModel`): AI SDK language model to use for title extraction
 
 **nodes** (`number`): Number of title nodes to extract
 
@@ -56,15 +56,15 @@ The `extract` parameter accepts the following fields:
 
 ### `SummaryExtractArgs`
 
-**llm** (`MastraLanguageModel`): AI SDK language model to use for summary extraction
+**llm** (`MastraLanguageModel | MastraLegacyLanguageModel`): AI SDK language model to use for summary extraction
 
-**summaries** (`('self' | 'prev' | 'next')[]`): List of summary types to generate. Can only include 'self' (current chunk), 'prev' (previous chunk), or 'next' (next chunk)
+**summaries** (`string[]`): List of summary types to generate. Defaults to \['self']. Supported values are 'self' (current chunk), 'prev' (previous chunk), and 'next' (next chunk).
 
 **promptTemplate** (`string`): Custom prompt template for summary generation. Must include {context} placeholder
 
 ### `QuestionAnswerExtractArgs`
 
-**llm** (`MastraLanguageModel`): AI SDK language model to use for question generation
+**llm** (`MastraLanguageModel | MastraLegacyLanguageModel`): AI SDK language model to use for question generation
 
 **questions** (`number`): Number of questions to generate
 
@@ -74,7 +74,7 @@ The `extract` parameter accepts the following fields:
 
 ### `KeywordExtractArgs`
 
-**llm** (`MastraLanguageModel`): AI SDK language model to use for keyword extraction
+**llm** (`MastraLanguageModel | MastraLegacyLanguageModel`): AI SDK language model to use for keyword extraction
 
 **keywords** (`number`): Number of keywords to extract
 

package/dist/docs/references/reference-rag-graph-rag-guide.md

@@ -23,7 +23,7 @@ For straightforward semantic search without relationship traversal, use [standar
 GraphRAG combines vector similarity with knowledge graph traversal:
 
 1. Initial vector search retrieves relevant chunks based on semantic similarity
-2. A knowledge graph is constructed from the retrieved chunks
+2. On the tool's first execution, a knowledge graph is constructed from the retrieved chunks. Later queries reuse this graph
 3. The graph is traversed to find connected information
 4. Results include both directly relevant chunks and related content
 

package/dist/docs/references/reference-rag-graph-rag.md

@@ -83,7 +83,7 @@ Returns an array of `RankedNode` objects, where each node contains:
 
 **content** (`string`): Text content of the document chunk
 
-**metadata** (`Record<string, any>`): Additional metadata associated with the chunk
+**metadata** (`Record<string, any>`): Additional metadata associated with the chunk, when present
 
 **score** (`number`): Combined relevance score from graph traversal
 

package/dist/docs/references/reference-rag-rerank.md

@@ -10,17 +10,18 @@ The `rerank()` function provides advanced reranking capabilities for vector sear
 function rerank(
   results: QueryResult[],
   query: string,
-  modelConfig: ModelConfig,
-  options?: RerankerFunctionOptions,
+  model: MastraLanguageModel,
+  options: RerankerFunctionOptions,
 ): Promise<RerankResult[]>
 ```
 
 ## Usage example
 
 ```typescript
+import { ModelRouterLanguageModel } from '@mastra/core/llm'
 import { rerank } from '@mastra/rag'
 
-const model = 'openai/gpt-5.6-sol'
+const model = new ModelRouterLanguageModel('openai/gpt-5.6-sol')
 
 const rerankedResults = await rerank(vectorSearchResults, 'How do I deploy to production?', model, {
   weights: {
@@ -64,7 +65,7 @@ The function returns an array of `RerankResult` objects:
 
 **result** (`QueryResult`): The original query result
 
-**score** (`number`): Combined reranking score (0-1)
+**score** (`number`): Combined reranking score. Usually between 0 and 1, but query-based adjustments can raise it slightly above 1.
 
 **details** (`ScoringDetails`): Detailed scoring information
 

package/dist/docs/references/reference-rag-rerankWithScorer.md

@@ -11,7 +11,7 @@ function rerankWithScorer({
   results: QueryResult[],
   query: string,
   scorer: RelevanceScoreProvider,
-  options?: RerankerFunctionOptions,
+  options: RerankerFunctionOptions,
 }): Promise<RerankResult[]>;
 ```
 
@@ -69,7 +69,7 @@ The function returns an array of `RerankResult` objects:
 
 **result** (`QueryResult`): The original query result
 
-**score** (`number`): Combined reranking score (0-1)
+**score** (`number`): Combined reranking score. Usually between 0 and 1, but query-based adjustments can raise it slightly above 1.
 
 **details** (`ScoringDetails`): Detailed scoring information
 

package/dist/docs/references/reference-rag-retrieval.md

@@ -50,23 +50,25 @@ console.log(results)
 
 The `topK` parameter specifies the maximum number of most similar results to return from the vector search.
 
-Results include both the text content and a similarity score:
+Each result includes an `id`, a similarity `score`, and the stored `metadata`. When you store chunk text in metadata, it's available as `metadata.text`:
 
 ```ts
 [
   {
-    text: 'Climate change poses significant challenges...',
+    id: 'chunk-1',
     score: 0.89,
-    metadata: { source: 'article1.txt' },
+    metadata: { text: 'Climate change poses significant challenges...', source: 'article1.txt' },
   },
   {
-    text: 'Rising temperatures affect crop yields...',
+    id: 'chunk-2',
     score: 0.82,
-    metadata: { source: 'article1.txt' },
+    metadata: { text: 'Rising temperatures affect crop yields...', source: 'article1.txt' },
   },
 ]
 ```
 
+Results can also include `vector` when you set `includeVector: true`, and `document` when the store returns the original document (Chroma only).
+
 ## Advanced retrieval options
 
 ### Metadata Filtering

package/dist/docs/references/reference-tools-document-chunker-tool.md

@@ -20,9 +20,9 @@ const chunker = createDocumentChunkerTool({
   doc: document,
   params: {
     strategy: 'recursive',
-    size: 512,
+    maxSize: 512,
     overlap: 50,
-    separator: '\n',
+    separators: ['\n'],
   },
 })
 
@@ -39,11 +39,11 @@ const { chunks } = await chunker.execute()
 
 **strategy** (`'recursive'`): The chunking strategy to use (Default: `'recursive'`)
 
-**size** (`number`): Target size of each chunk in tokens/characters (Default: `512`)
+**maxSize** (`number`): Maximum size of each chunk in tokens/characters (Default: `512`)
 
 **overlap** (`number`): Number of overlapping tokens/characters between chunks (Default: `50`)
 
-**separator** (`string`): Character(s) to use as chunk separator (Default: `'\n'`)
+**separators** (`string[]`): Separators to split on, in order of priority (recursive strategy) (Default: `['\n']`)
 
 ## Returns
 
@@ -64,9 +64,9 @@ const chunker = createDocumentChunkerTool({
   doc: technicalDoc,
   params: {
     strategy: 'recursive',
-    size: 1024, // Larger chunks
+    maxSize: 1024, // Larger chunks
     overlap: 100, // More overlap
-    separator: '\n\n', // Split on double newlines
+    separators: ['\n\n'], // Split on double newlines
   },
 })
 
@@ -82,8 +82,8 @@ chunks.forEach((chunk, index) => {
 
 The chunker is created as a Mastra tool with the following properties:
 
-- **Tool ID**: `Document Chunker {strategy} {size}`
-- **Description**: `Chunks document using {strategy} strategy with size {size} and {overlap} overlap`
+- **Tool ID**: `Document Chunker {strategy} {maxSize}`
+- **Description**: `Chunks document using {strategy} strategy with maxSize {maxSize} and {overlap} overlap`
 - **Input Schema**: Empty object (no additional inputs required)
 - **Output Schema**: Object containing the chunks array
 

package/dist/docs/references/reference-tools-vector-query-tool.md

@@ -21,13 +21,13 @@ const queryTool = createVectorQueryTool({
 
 ## Parameters
 
-> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `model`, `id`, and `description` can only be set at creation time.
+> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `id` and `description` can only be set at creation time.
 
-**id** (`string`): Custom ID for the tool. By default: 'VectorQuery {vectorStoreName} {indexName} Tool'. (Set at creation only.)
+**id** (`string`): Custom ID for the tool. By default: 'VectorQuery {vectorStoreName} {indexName} Tool', where {vectorStoreName} is 'DirectVectorStore' when a vectorStore instance is passed without a vectorStoreName. (Set at creation only.)
 
 **description** (`string`): Custom description for the tool. By default: 'Access the knowledge base to find information needed to answer user questions' (Set at creation only.)
 
-**model** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
+**model** (`EmbeddingModel`): Embedding model to use for vector search. (Can be set at creation or overridden at runtime via the request context.)
 
 **vectorStoreName** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
 
@@ -47,7 +47,7 @@ const queryTool = createVectorQueryTool({
 
 **reranker.options.weights** (`WeightConfig`): Weights for scoring components (semantic: 0.4, vector: 0.4, position: 0.2)
 
-**reranker.options.topK** (`number`): Number of top results to return
+**reranker.options.topK** (`number`): Number of top results to return after reranking. Falls back to the query's topK (from the request context, the tool input, or 10) when unset or 0.
 
 **databaseConfig** (`DatabaseConfig`): Database-specific configuration options for optimizing queries. (Can be set at creation or overridden at runtime.)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/rag",
-  "version": "2.6.7-alpha.0",
+  "version": "2.6.8-alpha.0",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -50,10 +50,10 @@
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
     "zod": "^4.6.4",
-    "@internal/ai-sdk-v4": "0.0.88",
-    "@internal/lint": "0.0.141",
-    "@internal/types-builder": "0.0.116",
-    "@mastra/core": "1.76.0-alpha.1"
+    "@internal/lint": "0.0.144",
+    "@internal/ai-sdk-v4": "0.0.91",
+    "@internal/types-builder": "0.0.119",
+    "@mastra/core": "1.78.1-alpha.0"
   },
   "keywords": [
     "rag",