@mastra/rag 2.6.6 → 2.6.7

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.6"
+  version: "2.6.7"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.6.6",
+  "version": "2.6.7",
   "package": "@mastra/rag",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-guides-context-engineering.md

@@ -210,8 +210,6 @@ Observations are added in stable chunks, which helps providers reuse the existin
 
 ## Signals
 
-> **Beta:** Signals may change without a major version bump until the API is stable.
-
 [Signals](https://mastra.ai/docs/harness/signals) add messages or system-generated context to a memory-backed thread. Delivery depends on the thread's state: a signal can wake an idle agent or enter an active loop. It can also wait for the next turn or persist without waking the agent.
 
 State signals require memory and an existing thread. Notification inbox signals require a storage adapter with notification support.

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-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/index.cjs

@@ -634,7 +634,7 @@ var UnsupportedFunctionalityError = class extends AISDKError {
 };
 _a14 = symbol14;
 //#endregion
-//#region ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@/nanoid/3.3.19/bb8b18de8c5719d31b4e1eca475b7409a05b078fc371f92d1bbba7aa803c85d0/node_modules/nanoid/non-secure/index.js
+//#region ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@/nanoid/5.1.16/f16424b532a5e69aacddcb2977ac17378b6f79695bbd27ead3d90c703848f22f/node_modules/nanoid/non-secure/index.js
 let customAlphabet = (alphabet, defaultSize = 21) => {
 	return (size = defaultSize) => {
 		let id = "";
@@ -644,7 +644,7 @@ let customAlphabet = (alphabet, defaultSize = 21) => {
 	};
 };
 //#endregion
-//#region ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@ai-sdk/provider-utils/2.2.8/52151efd10e124b032de4a62b4d25d0e5353c6829a00b02bce7f27fe8c7063b7/node_modules/@ai-sdk/provider-utils/dist/index.mjs
+//#region ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@ai-sdk/provider-utils/2.2.8/fd79a5c5f5d36120acbfd746754884c17798c35178b46bd11cca9dff89c013d2/node_modules/@ai-sdk/provider-utils/dist/index.mjs
 var import_secure_json_parse = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	const hasBuffer = typeof Buffer !== "undefined";
 	const suspectProtoRx = /"(?:_|\\u005[Ff])(?:_|\\u005[Ff])(?:p|\\u0070)(?:r|\\u0072)(?:o|\\u006[Ff])(?:t|\\u0074)(?:o|\\u006[Ff])(?:_|\\u005[Ff])(?:_|\\u005[Ff])"\s*:/;
@@ -1187,7 +1187,7 @@ function withoutTrailingSlash(url) {
 	return url == null ? void 0 : url.replace(/\/$/, "");
 }
 //#endregion
-//#region ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@ai-sdk/openai/1.3.24/312581640555a819e614bdf1b3844a7ef4b79558f9ec4d5dbd71d5b6eb519752/node_modules/@ai-sdk/openai/dist/index.mjs
+//#region ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@ai-sdk/openai/1.3.24/016fac41d998ff168d98fde7926aa7713f8ffc38160a6b4427bfdc41fae1bc99/node_modules/@ai-sdk/openai/dist/index.mjs
 function convertToOpenAIChatMessages({ prompt, useLegacyFunctionCalling = false, systemMessageMode = "system" }) {
 	const messages = [];
 	const warnings = [];
@@ -6088,8 +6088,8 @@ var MDocument = class MDocument {
 			attributes: {
 				action: "chunk",
 				strategy,
-				chunkSize: chunkOptions?.size,
-				chunkOverlap: chunkOptions?.overlap
+				chunkSize: "maxSize" in chunkOptions ? chunkOptions.maxSize : void 0,
+				chunkOverlap: "overlap" in chunkOptions ? chunkOptions.overlap : void 0
 			}
 		});
 		try {