@mastra/rag 2.7.3-alpha.0 → 2.7.3-alpha.2

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.0"
+  version: "2.7.3-alpha.2"
 ---
 
 ## 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,5 +1,5 @@
 {
-  "version": "2.7.3-alpha.0",
+  "version": "2.7.3-alpha.2",
   "package": "@mastra/rag",
   "exports": {
     "CohereRelevanceScorer": {
@@ -10,7 +10,7 @@
     "GraphRAG": {
       "types": "dist/graph-rag/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6277
+      "line": 6293
     },
     "Language": {
       "types": "dist/document/types.d.ts",
@@ -35,57 +35,57 @@
     "createBedrockKBTool": {
       "types": "dist/tools/bedrock-knowledge-base.d.ts",
       "implementation": "dist/index.js",
-      "line": 7114
+      "line": 7138
     },
     "createDocumentChunkerTool": {
       "types": "dist/tools/document-chunker.d.ts",
       "implementation": "dist/index.js",
-      "line": 6498
+      "line": 6529
     },
     "createGraphRAGTool": {
       "types": "dist/tools/graph-rag.d.ts",
       "implementation": "dist/index.js",
-      "line": 6820
+      "line": 6844
     },
     "createVectorQueryTool": {
       "types": "dist/tools/vector-query.d.ts",
       "implementation": "dist/index.js",
-      "line": 6974
+      "line": 6998
     },
     "defaultGraphRagDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6645
+      "line": 6676
     },
     "defaultVectorQueryDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6644
+      "line": 6675
     },
     "filterDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6664
+      "line": 6695
     },
     "queryTextDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6646
+      "line": 6677
     },
     "rerank": {
       "types": "dist/rerank/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6264
+      "line": 6280
     },
     "rerankWithScorer": {
       "types": "dist/rerank/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6256
+      "line": 6272
     },
     "topKDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6654
+      "line": 6685
     }
   },
   "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
 
@@ -127,7 +127,7 @@ static deserialize(snapshot: GraphRAGSnapshot): GraphRAG
 
 **snapshot** (`GraphRAGSnapshot`): A snapshot previously returned by serialize
 
-Throws if the snapshot version is unsupported, if a node embedding doesn't match the snapshot dimension, or if an edge references a node that isn't in the snapshot. A bad snapshot therefore fails at load time instead of during a later query.
+Throws if the snapshot version is unsupported, if a node embedding doesn't match the snapshot dimension or contains non-finite values, or if an edge references a node that isn't in the snapshot. A bad snapshot therefore fails at load time instead of during a later query.
 
 ## Persisting a graph
 

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

@@ -43,7 +43,7 @@ const rerankedResults = await rerank(vectorSearchResults, 'How do I deploy to pr
 
 **options** (`RerankerFunctionOptions`): Options for the reranking model
 
-**options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1)
+**options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1; each weight must be between 0 and 1)
 
 **options.weights.semantic** (`number (default: 0.4)`): Weight for semantic relevance
 

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

@@ -47,7 +47,7 @@ const rerankedResults = await rerank({
 
 **options** (`RerankerFunctionOptions`): Options for the reranking model
 
-**options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1)
+**options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1; each weight must be between 0 and 1)
 
 **options.weights.semantic** (`number (default: 0.4)`): Weight for semantic relevance
 

package/dist/graph-rag/index.d.ts

@@ -64,8 +64,9 @@ export declare class GraphRAG {
     /**
      * Rebuild a GraphRAG instance from a snapshot produced by `serialize()`.
      *
-     * @throws if the snapshot version is unsupported, a node embedding does not
-     * match the snapshot dimension, or an edge references an unknown node.
+     * @throws if the snapshot version is unsupported, a node ID is duplicated,
+     * a node embedding does not match the snapshot dimension or contains nonfinite values,
+     * or an edge references an unknown node.
      */
     static deserialize(snapshot: GraphRAGSnapshot): GraphRAG;
     clear(): void;

package/dist/graph-rag/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph-rag/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,KAAK,iBAAiB,GAAG,UAAU,CAAC;AACpC,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAGzC,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAID,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAE1B,YAAY,SAAS,GAAE,MAAa,EAAE,SAAS,GAAE,MAAY,EAK5D;IAGD,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAQ7B;IAGD,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAY7B;IAGD,QAAQ,IAAI,SAAS,EAAE,CAEtB;IAGD,QAAQ,IAAI,SAAS,EAAE,CAEtB;IAED,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAExC;IAED;;;;;;;;OAQG;IACH,SAAS,IAAI,gBAAgB,CAY5B;IAED;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,QAAQ,CA+BvD;IAED,KAAK,IAAI,IAAI,CAGZ;IAED,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAMtD;IAGD,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,gBAAgB;IAgCxB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE,QAqC7D;IAED,OAAO,CAAC,sBAAsB;IAoB9B,OAAO,CAAC,qBAAqB;IA2C7B;;;;;;;;OAQG;IAEH,KAAK,CAAC,EACJ,KAAK,EACL,IAAS,EACT,eAAqB,EACrB,WAAkB,EAClB,MAAM,GACP,EAAE;QACD,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;KACjC,GAAG,UAAU,EAAE,CA8Df;CACF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph-rag/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,KAAK,iBAAiB,GAAG,UAAU,CAAC;AACpC,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAGzC,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAID,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAE1B,YAAY,SAAS,GAAE,MAAa,EAAE,SAAS,GAAE,MAAY,EAK5D;IAGD,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAa7B;IAGD,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAiB7B;IAGD,QAAQ,IAAI,SAAS,EAAE,CAKtB;IAGD,QAAQ,IAAI,SAAS,EAAE,CAEtB;IAED,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAExC;IAED;;;;;;;;OAQG;IACH,SAAS,IAAI,gBAAgB,CAY5B;IAED;;;;;;OAMG;IACH,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,QAAQ,CAqCvD;IAED,KAAK,IAAI,IAAI,CAGZ;IAED,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAMtD;IAGD,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,gBAAgB;IAgCxB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE,QAwC7D;IAED,OAAO,CAAC,sBAAsB;IAoB9B,OAAO,CAAC,qBAAqB;IA2C7B;;;;;;;;OAQG;IAEH,KAAK,CAAC,EACJ,KAAK,EACL,IAAS,EACT,eAAqB,EACrB,WAAkB,EAClB,MAAM,GACP,EAAE;QACD,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;KACjC,GAAG,UAAU,EAAE,CAmEf;CACF"}

package/dist/index.cjs

@@ -6210,9 +6210,25 @@ async function executeRerank({ results, query, scorer, options }) {
 		...DEFAULT_WEIGHTS,
 		...options.weights
 	};
+	for (const [name, weight] of Object.entries(weights)) if (!Number.isFinite(weight) || weight < 0 || weight > 1) {
+		const err = /* @__PURE__ */ new Error(`Weights must be finite numbers between 0 and 1. Got ${name}: ${weight}`);
+		rerankSpan?.error({
+			error: err,
+			endSpan: true
+		});
+		throw err;
+	}
 	const sum = Object.values(weights).reduce((acc, w) => acc.plus(w.toString()), new big_js.Big(0));
 	if (!sum.eq(1)) {
-		const err = /* @__PURE__ */ new Error(`Weights must add up to 1. Got ${sum} from ${weights}`);
+		const err = /* @__PURE__ */ new Error(`Weights must add up to 1. Got ${sum} from ${JSON.stringify(weights)}`);
+		rerankSpan?.error({
+			error: err,
+			endSpan: true
+		});
+		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
@@ -6290,12 +6306,17 @@ var GraphRAG = class GraphRAG {
 	addNode(node) {
 		if (!node.embedding) throw new Error("Node must have an embedding");
 		if (node.embedding.length !== this.dimension) throw new Error(`Embedding dimension must be ${this.dimension}`);
-		this.nodes.set(node.id, node);
+		for (const component of node.embedding) if (!Number.isFinite(component)) throw new Error("Embedding must contain only finite numbers");
+		this.nodes.set(node.id, {
+			...node,
+			embedding: [...node.embedding]
+		});
 	}
 	addEdge(edge) {
 		if (!this.nodes.has(edge.source) || !this.nodes.has(edge.target)) throw new Error("Both source and target nodes must exist");
+		if (!Number.isFinite(edge.weight)) throw new Error("Edge weight must be a finite number");
 		this.edges.push(edge);
-		this.edges.push({
+		if (edge.source !== edge.target) this.edges.push({
 			source: edge.target,
 			target: edge.source,
 			weight: edge.weight,
@@ -6303,7 +6324,10 @@ var GraphRAG = class GraphRAG {
 		});
 	}
 	getNodes() {
-		return Array.from(this.nodes.values());
+		return Array.from(this.nodes.values(), (node) => ({
+			...node,
+			...node.embedding ? { embedding: [...node.embedding] } : {}
+		}));
 	}
 	getEdges() {
 		return this.edges;
@@ -6336,20 +6360,25 @@ var GraphRAG = class GraphRAG {
 	/**
 	* Rebuild a GraphRAG instance from a snapshot produced by `serialize()`.
 	*
-	* @throws if the snapshot version is unsupported, a node embedding does not
-	* match the snapshot dimension, or an edge references an unknown node.
+	* @throws if the snapshot version is unsupported, a node ID is duplicated,
+	* a node embedding does not match the snapshot dimension or contains nonfinite values,
+	* or an edge references an unknown node.
 	*/
 	static deserialize(snapshot) {
 		if (snapshot?.version !== GRAPH_RAG_SNAPSHOT_VERSION) throw new Error(`Unsupported GraphRAG snapshot version: ${snapshot?.version}`);
 		const graph = new GraphRAG(snapshot.dimension, snapshot.threshold);
-		for (const node of snapshot.nodes ?? []) graph.addNode({
-			...node,
-			...node.embedding ? { embedding: [...node.embedding] } : {},
-			...node.metadata ? { metadata: structuredClone(node.metadata) } : {}
-		});
+		for (const node of snapshot.nodes ?? []) {
+			if (graph.nodes.has(node.id)) throw new Error(`Duplicate node id in snapshot: ${node.id}`);
+			graph.addNode({
+				...node,
+				...node.embedding ? { embedding: [...node.embedding] } : {},
+				...node.metadata ? { metadata: structuredClone(node.metadata) } : {}
+			});
+		}
 		for (const edge of snapshot.edges ?? []) {
 			if (!graph.nodes.has(edge.source)) throw new Error(`Edge references unknown node: ${edge.source}`);
 			if (!graph.nodes.has(edge.target)) throw new Error(`Edge references unknown node: ${edge.target}`);
+			if (!Number.isFinite(edge.weight)) throw new Error("Edge weight must be a finite number");
 		}
 		graph.edges = (snapshot.edges ?? []).map((edge) => ({ ...edge }));
 		return graph;
@@ -6391,22 +6420,21 @@ var GraphRAG = class GraphRAG {
 	createGraph(chunks, embeddings) {
 		if (!chunks?.length || !embeddings?.length) throw new Error("Chunks and embeddings arrays must not be empty");
 		if (chunks.length !== embeddings.length) throw new Error("Chunks and embeddings must have the same length");
+		const graph = new GraphRAG(this.dimension, this.threshold);
 		chunks.forEach((chunk, index) => {
-			const node = {
+			graph.addNode({
 				id: index.toString(),
 				content: chunk.text,
 				embedding: embeddings[index]?.vector,
 				metadata: { ...chunk.metadata }
-			};
-			this.addNode(node);
-			this.nodes.set(node.id, node);
+			});
 		});
 		for (let i = 0; i < chunks.length; i++) {
 			const firstEmbedding = embeddings[i]?.vector;
 			for (let j = i + 1; j < chunks.length; j++) {
 				const secondEmbedding = embeddings[j]?.vector;
 				const similarity = this.cosineSimilarity(firstEmbedding, secondEmbedding);
-				if (similarity > this.threshold) this.addEdge({
+				if (similarity > this.threshold) graph.addEdge({
 					source: i.toString(),
 					target: j.toString(),
 					weight: similarity,
@@ -6414,6 +6442,8 @@ var GraphRAG = class GraphRAG {
 				});
 			}
 		}
+		this.nodes = graph.nodes;
+		this.edges = graph.edges;
 	}
 	selectWeightedNeighbor(neighbors) {
 		const totalWeight = neighbors.reduce((sum, n) => sum + n.weight, 0);
@@ -6457,9 +6487,10 @@ var GraphRAG = class GraphRAG {
 	*/
 	query({ query, topK = 10, randomWalkSteps = 100, restartProb = .15, filter }) {
 		if (!query || query.length !== this.dimension) throw new Error(`Query embedding must have dimension ${this.dimension}`);
-		if (topK < 1) throw new Error("TopK must be greater than 0");
-		if (randomWalkSteps < 1) throw new Error("Random walk steps must be greater than 0");
-		if (restartProb <= 0 || restartProb >= 1) throw new Error("Restart probability must be between 0 and 1");
+		for (const component of query) if (!Number.isFinite(component)) throw new Error("Query embedding must contain only finite numbers");
+		if (!Number.isInteger(topK) || topK < 1) throw new Error("TopK must be a positive integer");
+		if (!Number.isInteger(randomWalkSteps) || randomWalkSteps < 1) throw new Error("Random walk steps must be a positive integer");
+		if (!Number.isFinite(restartProb) || restartProb <= 0 || restartProb >= 1) throw new Error("Restart probability must be between 0 and 1");
 		const filterEntries = Object.entries(filter ?? {});
 		const matchesFilter = (node) => filterEntries.length === 0 ? true : filterEntries.every(([key, value]) => node.metadata?.[key] === value);
 		const nodesToSearch = Array.from(this.nodes.values()).filter(matchesFilter);
@@ -6752,15 +6783,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) {