@mastra/rag 2.7.2 → 2.7.3-alpha.1

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.7.2"
+  version: "2.7.3-alpha.1"
 ---
 
 ## When to use
@@ -20,7 +20,6 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Reference
 
-- [RAG](references/reference-migrations-upgrade-to-v1-rag.md) - Migrate RAG code to Mastra v1 with renamed chunking parameters and narrowed option types, including updates to related document-processing APIs.
 - [Reference: .chunk()](references/reference-rag-chunk.md) - The .chunk() function splits documents into smaller segments using strategies and options.
 - [Chunking and embedding documents](references/reference-rag-chunking-and-embedding.md) - Chunk documents with MDocument, generate embeddings through the AI SDK, and prepare text and metadata for vector storage and RAG retrieval.
 - [Reference: DatabaseConfig](references/reference-rag-database-config.md) - The DatabaseConfig type allows you to specify database-specific configurations when using vector query tools.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,6 +1,92 @@
 {
-  "version": "2.7.2",
+  "version": "2.7.3-alpha.1",
   "package": "@mastra/rag",
-  "exports": {},
+  "exports": {
+    "CohereRelevanceScorer": {
+      "types": "dist/rerank/relevance/cohere/index.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6088
+    },
+    "GraphRAG": {
+      "types": "dist/graph-rag/index.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6285
+    },
+    "Language": {
+      "types": "dist/document/types.d.ts",
+      "implementation": "dist/index.js",
+      "line": 3842
+    },
+    "MDocument": {
+      "types": "dist/document/document.d.ts",
+      "implementation": "dist/index.js",
+      "line": 5821
+    },
+    "MastraAgentRelevanceScorer": {
+      "types": "dist/rerank/relevance/mastra-agent/index.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6123
+    },
+    "ZeroEntropyRelevanceScorer": {
+      "types": "dist/rerank/relevance/zeroentropy/index.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6152
+    },
+    "createBedrockKBTool": {
+      "types": "dist/tools/bedrock-knowledge-base.d.ts",
+      "implementation": "dist/index.js",
+      "line": 7115
+    },
+    "createDocumentChunkerTool": {
+      "types": "dist/tools/document-chunker.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6506
+    },
+    "createGraphRAGTool": {
+      "types": "dist/tools/graph-rag.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6821
+    },
+    "createVectorQueryTool": {
+      "types": "dist/tools/vector-query.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6975
+    },
+    "defaultGraphRagDescription": {
+      "types": "dist/utils/default-settings.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6653
+    },
+    "defaultVectorQueryDescription": {
+      "types": "dist/utils/default-settings.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6652
+    },
+    "filterDescription": {
+      "types": "dist/utils/default-settings.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6672
+    },
+    "queryTextDescription": {
+      "types": "dist/utils/default-settings.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6654
+    },
+    "rerank": {
+      "types": "dist/rerank/index.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6272
+    },
+    "rerankWithScorer": {
+      "types": "dist/rerank/index.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6264
+    },
+    "topKDescription": {
+      "types": "dist/utils/default-settings.d.ts",
+      "implementation": "dist/index.js",
+      "line": 6662
+    }
+  },
   "modules": {}
 }

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

@@ -103,7 +103,7 @@ serialize(): GraphRAGSnapshot
 
 Returns a `GraphRAGSnapshot` object containing:
 
-**version** (`number`): Snapshot format version, used to reject snapshots this version of the class can't load
+**version** (`1`): Snapshot format version. Always 1 in the current format, so deserialize rejects snapshots with any other version
 
 **dimension** (`number`): Dimension of the embedding vectors the graph was built with
 

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

@@ -88,14 +88,14 @@ The tool returns an object with:
 ```typescript
 {
   id: string;         // Unique chunk/document identifier
-  metadata: any;      // All metadata fields (document ID, etc.)
-  vector: number[];   // Embedding vector (if available)
+  metadata?: any;     // All metadata fields (document ID, etc.)
+  vector: number[];   // Embedding vector, or [] when unavailable
   score: number;      // Similarity score for this retrieval
   document: string;   // Full chunk/document text (if available)
 }
 ```
 
-`document` is only populated by vector stores whose `query()` returns document content, such as Chroma, Elasticsearch, LanceDB, and MongoDB. For other stores, such as PgVector, it's an empty string. Read the chunk text from `sources[i].metadata.text` (or whichever metadata key you stored it under).
+`document` is only populated by vector stores whose `query()` returns document content, such as Chroma, Elasticsearch, LanceDB, and MongoDB. For other stores, such as PgVector, it's an empty string. Read the chunk text from `sources[i].metadata?.text` (or whichever metadata key you stored it under). `metadata` is `undefined` when the store returns no metadata for a result.
 
 ## Default tool description
 

package/dist/document/transformers/character.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"character.d.ts","sourceRoot":"","sources":["../../../src/document/transformers/character.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAqEzC,qBAAa,oBAAqB,SAAQ,eAAe;IACvD,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC;IAEpC,YAAY,EAAE,SAAkB,EAAE,gBAAwB,EAAE,GAAG,WAAW,EAAE,GAAE,qBAA0B,EAIvG;IAED,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE,CAmB9C;IAED,OAAO,CAAC,YAAY;CAyDrB;AAED,qBAAa,6BAA8B,SAAQ,eAAe;IAChE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAC/B,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC;IAEpC,YAAY,EAAE,UAAU,EAAE,gBAAwB,EAAE,QAAQ,EAAE,GAAG,WAAW,EAAE,GAAE,qBAA0B,EAIzG;IAED,OAAO,CAAC,UAAU;IA8DlB,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE,CAE9C;IAED,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,gBAAqB,GAAG,6BAA6B,CAQrG;IAED,MAAM,CAAC,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,CAua5D;CACF"}
+{"version":3,"file":"character.d.ts","sourceRoot":"","sources":["../../../src/document/transformers/character.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAuEzC,qBAAa,oBAAqB,SAAQ,eAAe;IACvD,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC;IAEpC,YAAY,EAAE,SAAkB,EAAE,gBAAwB,EAAE,GAAG,WAAW,EAAE,GAAE,qBAA0B,EAIvG;IAED,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE,CAmB9C;IAED,OAAO,CAAC,YAAY;CAyDrB;AAED,qBAAa,6BAA8B,SAAQ,eAAe;IAChE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAC/B,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC;IAEpC,YAAY,EAAE,UAAU,EAAE,gBAAwB,EAAE,QAAQ,EAAE,GAAG,WAAW,EAAE,GAAE,qBAA0B,EAIzG;IAED,OAAO,CAAC,UAAU;IA8DlB,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE,CAE9C;IAED,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,gBAAqB,GAAG,6BAA6B,CAQrG;IAED,MAAM,CAAC,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,CAua5D;CACF"}

package/dist/index.cjs

@@ -4008,7 +4008,7 @@ var TextTransformer = class {
 };
 // src/document/transformers/character.ts
 function splitTextWithRegex(text, separator, separatorPosition) {
-	if (!separator) return text.split("");
+	if (!separator) return Array.from(text);
 	if (!text) return [];
 	const result = [];
 	let lastIndex = 0;
@@ -6219,6 +6219,14 @@ async function executeRerank({ results, query, scorer, options }) {
 		});
 		throw err;
 	}
+	if (!Number.isInteger(topK) || topK < 0) {
+		const err = /* @__PURE__ */ new Error(`topK must be a nonnegative integer. Got ${topK}`);
+		rerankSpan?.error({
+			error: err,
+			endSpan: true
+		});
+		throw err;
+	}
 	const resultLength = results.length;
 	const queryAnalysis = queryEmbedding ? analyzeQueryEmbedding(queryEmbedding) : null;
 	let scoredResults;
@@ -6752,15 +6760,8 @@ async function resolveVectorStore(options, context, logger) {
 	if (mastra) return mastra.getVector(vectorStoreName);
 }
 function coerceTopK(topK, defaultValue = 10) {
-	if (typeof topK === "number") {
-		if (Number.isFinite(topK) && topK > 0) return topK;
-		return defaultValue;
-	}
-	if (typeof topK === "string") {
-		const parsed = Number(topK);
-		if (Number.isFinite(parsed) && parsed > 0) return parsed;
-		return defaultValue;
-	}
+	const parsed = typeof topK === "string" ? Number(topK) : topK;
+	if (typeof parsed === "number" && Number.isFinite(parsed) && Math.floor(parsed) >= 1) return Math.floor(parsed);
 	return defaultValue;
 }
 function parseFilterValue(filter, logger) {