@mastra/rag 2.7.3-alpha.2 → 2.8.0-alpha.3

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.3-alpha.2"
+  version: "2.8.0-alpha.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,91 +1,91 @@
 {
-  "version": "2.7.3-alpha.2",
+  "version": "2.8.0-alpha.3",
   "package": "@mastra/rag",
   "exports": {
     "CohereRelevanceScorer": {
       "types": "dist/rerank/relevance/cohere/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6088
+      "line": 6091
     },
     "GraphRAG": {
       "types": "dist/graph-rag/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6293
+      "line": 6296
     },
     "Language": {
       "types": "dist/document/types.d.ts",
       "implementation": "dist/index.js",
-      "line": 3842
+      "line": 3843
     },
     "MDocument": {
       "types": "dist/document/document.d.ts",
       "implementation": "dist/index.js",
-      "line": 5821
+      "line": 5824
     },
     "MastraAgentRelevanceScorer": {
       "types": "dist/rerank/relevance/mastra-agent/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6123
+      "line": 6126
     },
     "ZeroEntropyRelevanceScorer": {
       "types": "dist/rerank/relevance/zeroentropy/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6152
+      "line": 6155
     },
     "createBedrockKBTool": {
       "types": "dist/tools/bedrock-knowledge-base.d.ts",
       "implementation": "dist/index.js",
-      "line": 7138
+      "line": 7142
     },
     "createDocumentChunkerTool": {
       "types": "dist/tools/document-chunker.d.ts",
       "implementation": "dist/index.js",
-      "line": 6529
+      "line": 6532
     },
     "createGraphRAGTool": {
       "types": "dist/tools/graph-rag.d.ts",
       "implementation": "dist/index.js",
-      "line": 6844
+      "line": 6848
     },
     "createVectorQueryTool": {
       "types": "dist/tools/vector-query.d.ts",
       "implementation": "dist/index.js",
-      "line": 6998
+      "line": 7002
     },
     "defaultGraphRagDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6676
+      "line": 6679
     },
     "defaultVectorQueryDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6675
+      "line": 6678
     },
     "filterDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6695
+      "line": 6698
     },
     "queryTextDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6677
+      "line": 6680
     },
     "rerank": {
       "types": "dist/rerank/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6280
+      "line": 6283
     },
     "rerankWithScorer": {
       "types": "dist/rerank/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6272
+      "line": 6275
     },
     "topKDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6685
+      "line": 6688
     }
   },
   "modules": {}

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

@@ -200,7 +200,7 @@ When using the `headers` option, the markdown strategy ignores all general optio
 
 ### JSON
 
-**maxSize** (`number`): Maximum size of each chunk
+**maxSize** (`number`): Target maximum size of each JSON chunk. Must be at least 21. Long values nested in objects can produce larger chunks.
 
 **minSize** (`number`): Accepted for compatibility. Has no effect on JSON chunking: chunks smaller than this are kept, so no data is discarded.
 

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

@@ -23,10 +23,12 @@ 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. On the tool's first execution, a knowledge graph is constructed from the retrieved chunks. Later queries reuse this graph
+2. When retrieval finds chunks, the tool builds a knowledge graph from that request's chunks. The graph isn't reused across requests
 3. The graph is traversed to find connected information
 4. Results include both directly relevant chunks and related content
 
+If retrieval finds no chunks, the tool returns empty context and sources without building a graph.
+
 This process helps surface information that might not be semantically similar to the query but is contextually relevant through connections.
 
 ## Creating a graph query tool

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

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/document/transformers/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,YAAY,CAAU;IAE9B,YAAY,EAAE,OAAc,EAAE,WAAmB,EAAE,YAAmB,EAAE,EAAE,gBAAgB,EAIzF;IAED,OAAO,CAAC,MAAM,CAAC,QAAQ;IAoCvB;;OAEG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiC/D;IAED;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAS5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAU/B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAyC5B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;OAGG;IACH,OAAO,CAAC,WAAW;IA2DnB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAgE1B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAuBvB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAuDjB;;OAEG;IACH,SAAS,CAAC,EACR,QAAQ,EACR,YAAoB,GACrB,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAUxB;IAED;;OAEG;IACH,SAAS,CAAC,EACR,QAAQ,EACR,YAAoB,EACpB,WAAkB,GACnB,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,GAAG,MAAM,EAAE,CAcX;IAED;;OAEG;IACH,eAAe,CAAC,EACd,KAAK,EACL,YAAoB,EACpB,WAAkB,EAClB,SAAS,GACV,EAAE;QACD,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;KACnC,GAAG,QAAQ,EAAE,CAkBb;IAED,kBAAkB,CAAC,EACjB,WAAW,EACX,SAAS,EACT,YAAY,GACb,EAAE;QACD,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,SAAS,EAAE,QAAQ,EAAE,CAAC;KACvB,GAAG,QAAQ,EAAE,CAgBb;CACF"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/document/transformers/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,YAAY,CAAU;IAE9B,YAAY,EAAE,OAAc,EAAE,WAAmB,EAAE,YAAmB,EAAE,EAAE,gBAAgB,EAQzF;IAED,OAAO,CAAC,MAAM,CAAC,QAAQ;IAoCvB;;OAEG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiC/D;IAED;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAS5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAU/B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAyC5B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;OAGG;IACH,OAAO,CAAC,WAAW;IA2DnB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAgE1B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAuBvB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAuDjB;;OAEG;IACH,SAAS,CAAC,EACR,QAAQ,EACR,YAAoB,GACrB,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAUxB;IAED;;OAEG;IACH,SAAS,CAAC,EACR,QAAQ,EACR,YAAoB,EACpB,WAAkB,GACnB,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,GAAG,MAAM,EAAE,CAcX;IAED;;OAEG;IACH,eAAe,CAAC,EACd,KAAK,EACL,YAAoB,EACpB,WAAkB,EAClB,SAAS,GACV,EAAE;QACD,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;KACnC,GAAG,QAAQ,EAAE,CAkBb;IAED,kBAAkB,CAAC,EACjB,WAAW,EACX,SAAS,EACT,YAAY,GACb,EAAE;QACD,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,SAAS,EAAE,QAAQ,EAAE,CAAC;KACvB,GAAG,QAAQ,EAAE,CAgBb;CACF"}

package/dist/document/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/document/validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAsH7C,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,CAwB9E"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/document/validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAuH7C,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,CAwB9E"}

package/dist/index.cjs

@@ -33,6 +33,7 @@ let zeroentropy = require("zeroentropy");
 zeroentropy = __toESM(zeroentropy, 1);
 let _mastra_core_tools = require("@mastra/core/tools");
 let _mastra_core_vector = require("@mastra/core/vector");
+let _mastra_core_utils = require("@mastra/core/utils");
 let _aws_sdk_client_bedrock_agent_runtime = require("@aws-sdk/client-bedrock-agent-runtime");
 // src/document/prompts/format.ts
 function format(str, params) {
@@ -4849,6 +4850,7 @@ var RecursiveJsonTransformer = class RecursiveJsonTransformer {
 	ensureAscii;
 	convertLists;
 	constructor({ maxSize = 2e3, ensureAscii = false, convertLists = true }) {
+		if (!Number.isFinite(maxSize) || maxSize < 21) throw new RangeError("JSON maxSize must be at least 21");
 		this.maxSize = maxSize;
 		this.ensureAscii = ensureAscii;
 		this.convertLists = convertLists;
@@ -5781,6 +5783,7 @@ const validationSchemas = {
 		disallowedSpecial: setOrAllSchema
 	}).strict(),
 	json: baseChunkOptionsSchema.extend({
+		maxSize: zod.z.number().min(21).optional(),
 		minSize: zod.z.number().positive().optional(),
 		ensureAscii: zod.z.boolean().optional(),
 		convertLists: zod.z.boolean().optional()
@@ -6748,7 +6751,8 @@ async function resolveVectorStore(options, context, logger) {
 		if (typeof vectorStoreOption === "function") {
 			const resolved = await vectorStoreOption({
 				requestContext,
-				mastra
+				mastra,
+				user: (0, _mastra_core_utils.getRequestUser)(requestContext)
 			});
 			if (!isValidMastraVector(resolved)) {
 				const contextStr = buildContextString(context);
@@ -6852,8 +6856,6 @@ const createGraphRAGTool = (options) => {
 		...defaultGraphOptions,
 		...options.graphOptions || {}
 	};
-	const graphRag = new GraphRAG(graphOptions.dimension, graphOptions.threshold);
-	let isInitialized = false;
 	const inputSchema = options.enableFilter ? filterSchema : zod.z.object(baseSchema).passthrough();
 	return (0, _mastra_core_tools.createTool)({
 		id: toolId,
@@ -6913,38 +6915,40 @@ const createGraphRAGTool = (options) => {
 					observabilityContext
 				});
 				if (logger) logger.debug("vectorQuerySearch returned results", { count: results.length });
-				if (!isInitialized) {
-					const chunks = results.map((result) => ({
-						text: result?.metadata?.text,
-						metadata: result.metadata ?? {}
-					}));
-					const embeddings = results.map((result) => ({ vector: result.vector || [] }));
-					if (logger) logger.debug("Initializing graph", {
-						chunkCount: chunks.length,
-						embeddingCount: embeddings.length
-					});
-					const buildSpan = parentSpan?.createChildSpan({
-						type: _mastra_core_observability.SpanType.GRAPH_ACTION,
-						name: "graph build",
-						input: { nodeCount: chunks.length },
-						attributes: {
-							action: "build",
-							nodeCount: chunks.length,
-							threshold: graphOptions.threshold
-						}
-					});
-					try {
-						graphRag.createGraph(chunks, embeddings);
-					} catch (err) {
-						buildSpan?.error({
-							error: err,
-							endSpan: true
-						});
-						throw err;
+				if (results.length === 0) return {
+					relevantContext: [],
+					sources: []
+				};
+				const graphRag = new GraphRAG(graphOptions.dimension, graphOptions.threshold);
+				const chunks = results.map((result) => ({
+					text: result?.metadata?.text,
+					metadata: result.metadata ?? {}
+				}));
+				const embeddings = results.map((result) => ({ vector: result.vector || [] }));
+				if (logger) logger.debug("Initializing graph", {
+					chunkCount: chunks.length,
+					embeddingCount: embeddings.length
+				});
+				const buildSpan = parentSpan?.createChildSpan({
+					type: _mastra_core_observability.SpanType.GRAPH_ACTION,
+					name: "graph build",
+					input: { nodeCount: chunks.length },
+					attributes: {
+						action: "build",
+						nodeCount: chunks.length,
+						threshold: graphOptions.threshold
 					}
-					buildSpan?.end();
-					isInitialized = true;
-				} else if (logger) logger.debug("Graph already initialized, skipping graph construction");
+				});
+				try {
+					graphRag.createGraph(chunks, embeddings);
+				} catch (err) {
+					buildSpan?.error({
+						error: err,
+						endSpan: true
+					});
+					throw err;
+				}
+				buildSpan?.end();
 				const traverseSpan = parentSpan?.createChildSpan({
 					type: _mastra_core_observability.SpanType.GRAPH_ACTION,
 					name: "graph traverse",