@mastra/rag 2.7.3-alpha.1 → 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.1"
+  version: "2.7.3-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.7.3-alpha.1",
+  "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": 6285
+      "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": 7115
+      "line": 7138
     },
     "createDocumentChunkerTool": {
       "types": "dist/tools/document-chunker.d.ts",
       "implementation": "dist/index.js",
-      "line": 6506
+      "line": 6529
     },
     "createGraphRAGTool": {
       "types": "dist/tools/graph-rag.d.ts",
       "implementation": "dist/index.js",
-      "line": 6821
+      "line": 6844
     },
     "createVectorQueryTool": {
       "types": "dist/tools/vector-query.d.ts",
       "implementation": "dist/index.js",
-      "line": 6975
+      "line": 6998
     },
     "defaultGraphRagDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6653
+      "line": 6676
     },
     "defaultVectorQueryDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6652
+      "line": 6675
     },
     "filterDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6672
+      "line": 6695
     },
     "queryTextDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6654
+      "line": 6677
     },
     "rerank": {
       "types": "dist/rerank/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6272
+      "line": 6280
     },
     "rerankWithScorer": {
       "types": "dist/rerank/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 6264
+      "line": 6272
     },
     "topKDescription": {
       "types": "dist/utils/default-settings.d.ts",
       "implementation": "dist/index.js",
-      "line": 6662
+      "line": 6685
     }
   },
   "modules": {}

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

@@ -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,17 @@ 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
@@ -6298,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,
@@ -6311,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;
@@ -6344,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;
@@ -6399,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,
@@ -6422,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);
@@ -6465,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);