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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/dist/docs/SKILL.md +1 -1
  2. package/dist/docs/assets/SOURCE_MAP.json +18 -18
  3. package/dist/docs/references/reference-rag-chunk.md +1 -1
  4. package/dist/docs/references/reference-rag-graph-rag-guide.md +3 -1
  5. package/dist/docs/references/reference-rag-graph-rag.md +1 -1
  6. package/dist/docs/references/reference-rag-rerank.md +1 -1
  7. package/dist/docs/references/reference-rag-rerankWithScorer.md +1 -1
  8. package/dist/document/transformers/json.d.ts.map +1 -1
  9. package/dist/document/validation.d.ts.map +1 -1
  10. package/dist/graph-rag/index.d.ts +3 -2
  11. package/dist/graph-rag/index.d.ts.map +1 -1
  12. package/dist/index.cjs +80 -53
  13. package/dist/index.cjs.map +1 -1
  14. package/dist/index.js +80 -53
  15. package/dist/index.js.map +1 -1
  16. package/dist/rerank/index.d.ts.map +1 -1
  17. package/dist/tools/graph-rag.d.ts.map +1 -1
  18. package/dist/tools/types.d.ts +3 -0
  19. package/dist/tools/types.d.ts.map +1 -1
  20. package/dist/utils/tool-helpers.d.ts.map +1 -1
  21. package/package.json +4 -4
package/dist/docs/SKILL.md CHANGED
@@ -3,7 +3,7 @@ name: mastra-rag
3
3
  description: Documentation for @mastra/rag. Use when working with @mastra/rag APIs, configuration, or implementation.
4
4
  metadata:
5
5
  package: "@mastra/rag"
6
- version: "2.7.3-alpha.1"
6
+ version: "2.8.0-alpha.3"
7
7
  ---
8
8
 
9
9
  ## When to use
package/dist/docs/assets/SOURCE_MAP.json CHANGED
@@ -1,91 +1,91 @@
1
1
  {
2
- "version": "2.7.3-alpha.1",
2
+ "version": "2.8.0-alpha.3",
3
3
  "package": "@mastra/rag",
4
4
  "exports": {
5
5
  "CohereRelevanceScorer": {
6
6
  "types": "dist/rerank/relevance/cohere/index.d.ts",
7
7
  "implementation": "dist/index.js",
8
- "line": 6088
8
+ "line": 6091
9
9
  },
10
10
  "GraphRAG": {
11
11
  "types": "dist/graph-rag/index.d.ts",
12
12
  "implementation": "dist/index.js",
13
- "line": 6285
13
+ "line": 6296
14
14
  },
15
15
  "Language": {
16
16
  "types": "dist/document/types.d.ts",
17
17
  "implementation": "dist/index.js",
18
- "line": 3842
18
+ "line": 3843
19
19
  },
20
20
  "MDocument": {
21
21
  "types": "dist/document/document.d.ts",
22
22
  "implementation": "dist/index.js",
23
- "line": 5821
23
+ "line": 5824
24
24
  },
25
25
  "MastraAgentRelevanceScorer": {
26
26
  "types": "dist/rerank/relevance/mastra-agent/index.d.ts",
27
27
  "implementation": "dist/index.js",
28
- "line": 6123
28
+ "line": 6126
29
29
  },
30
30
  "ZeroEntropyRelevanceScorer": {
31
31
  "types": "dist/rerank/relevance/zeroentropy/index.d.ts",
32
32
  "implementation": "dist/index.js",
33
- "line": 6152
33
+ "line": 6155
34
34
  },
35
35
  "createBedrockKBTool": {
36
36
  "types": "dist/tools/bedrock-knowledge-base.d.ts",
37
37
  "implementation": "dist/index.js",
38
- "line": 7115
38
+ "line": 7142
39
39
  },
40
40
  "createDocumentChunkerTool": {
41
41
  "types": "dist/tools/document-chunker.d.ts",
42
42
  "implementation": "dist/index.js",
43
- "line": 6506
43
+ "line": 6532
44
44
  },
45
45
  "createGraphRAGTool": {
46
46
  "types": "dist/tools/graph-rag.d.ts",
47
47
  "implementation": "dist/index.js",
48
- "line": 6821
48
+ "line": 6848
49
49
  },
50
50
  "createVectorQueryTool": {
51
51
  "types": "dist/tools/vector-query.d.ts",
52
52
  "implementation": "dist/index.js",
53
- "line": 6975
53
+ "line": 7002
54
54
  },
55
55
  "defaultGraphRagDescription": {
56
56
  "types": "dist/utils/default-settings.d.ts",
57
57
  "implementation": "dist/index.js",
58
- "line": 6653
58
+ "line": 6679
59
59
  },
60
60
  "defaultVectorQueryDescription": {
61
61
  "types": "dist/utils/default-settings.d.ts",
62
62
  "implementation": "dist/index.js",
63
- "line": 6652
63
+ "line": 6678
64
64
  },
65
65
  "filterDescription": {
66
66
  "types": "dist/utils/default-settings.d.ts",
67
67
  "implementation": "dist/index.js",
68
- "line": 6672
68
+ "line": 6698
69
69
  },
70
70
  "queryTextDescription": {
71
71
  "types": "dist/utils/default-settings.d.ts",
72
72
  "implementation": "dist/index.js",
73
- "line": 6654
73
+ "line": 6680
74
74
  },
75
75
  "rerank": {
76
76
  "types": "dist/rerank/index.d.ts",
77
77
  "implementation": "dist/index.js",
78
- "line": 6272
78
+ "line": 6283
79
79
  },
80
80
  "rerankWithScorer": {
81
81
  "types": "dist/rerank/index.d.ts",
82
82
  "implementation": "dist/index.js",
83
- "line": 6264
83
+ "line": 6275
84
84
  },
85
85
  "topKDescription": {
86
86
  "types": "dist/utils/default-settings.d.ts",
87
87
  "implementation": "dist/index.js",
88
- "line": 6662
88
+ "line": 6688
89
89
  }
90
90
  },
91
91
  "modules": {}
package/dist/docs/references/reference-rag-chunk.md CHANGED
@@ -200,7 +200,7 @@ When using the `headers` option, the markdown strategy ignores all general optio
200
200
 
201
201
  ### JSON
202
202
 
203
- **maxSize** (`number`): Maximum size of each chunk
203
+ **maxSize** (`number`): Target maximum size of each JSON chunk. Must be at least 21. Long values nested in objects can produce larger chunks.
204
204
 
205
205
  **minSize** (`number`): Accepted for compatibility. Has no effect on JSON chunking: chunks smaller than this are kept, so no data is discarded.
206
206
 
package/dist/docs/references/reference-rag-graph-rag-guide.md CHANGED
@@ -23,10 +23,12 @@ For straightforward semantic search without relationship traversal, use [standar
23
23
  GraphRAG combines vector similarity with knowledge graph traversal:
24
24
 
25
25
  1. Initial vector search retrieves relevant chunks based on semantic similarity
26
- 2. On the tool's first execution, a knowledge graph is constructed from the retrieved chunks. Later queries reuse this graph
26
+ 2. When retrieval finds chunks, the tool builds a knowledge graph from that request's chunks. The graph isn't reused across requests
27
27
  3. The graph is traversed to find connected information
28
28
  4. Results include both directly relevant chunks and related content
29
29
 
30
+ If retrieval finds no chunks, the tool returns empty context and sources without building a graph.
31
+
30
32
  This process helps surface information that might not be semantically similar to the query but is contextually relevant through connections.
31
33
 
32
34
  ## Creating a graph query tool
package/dist/docs/references/reference-rag-graph-rag.md CHANGED
@@ -127,7 +127,7 @@ static deserialize(snapshot: GraphRAGSnapshot): GraphRAG
127
127
 
128
128
  **snapshot** (`GraphRAGSnapshot`): A snapshot previously returned by serialize
129
129
 
130
- 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.
130
+ 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.
131
131
 
132
132
  ## Persisting a graph
133
133
 
package/dist/docs/references/reference-rag-rerank.md CHANGED
@@ -43,7 +43,7 @@ const rerankedResults = await rerank(vectorSearchResults, 'How do I deploy to pr
43
43
 
44
44
  **options** (`RerankerFunctionOptions`): Options for the reranking model
45
45
 
46
- **options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1)
46
+ **options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1; each weight must be between 0 and 1)
47
47
 
48
48
  **options.weights.semantic** (`number (default: 0.4)`): Weight for semantic relevance
49
49
 
package/dist/docs/references/reference-rag-rerankWithScorer.md CHANGED
@@ -47,7 +47,7 @@ const rerankedResults = await rerank({
47
47
 
48
48
  **options** (`RerankerFunctionOptions`): Options for the reranking model
49
49
 
50
- **options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1)
50
+ **options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1; each weight must be between 0 and 1)
51
51
 
52
52
  **options.weights.semantic** (`number (default: 0.4)`): Weight for semantic relevance
53
53
 
package/dist/document/transformers/json.d.ts.map CHANGED
@@ -1 +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"}
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,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 CHANGED
@@ -1 +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"}
1
+ {"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/graph-rag/index.d.ts CHANGED
@@ -64,8 +64,9 @@ export declare class GraphRAG {
64
64
  /**
65
65
  * Rebuild a GraphRAG instance from a snapshot produced by `serialize()`.
66
66
  *
67
- * @throws if the snapshot version is unsupported, a node embedding does not
68
- * match the snapshot dimension, or an edge references an unknown node.
67
+ * @throws if the snapshot version is unsupported, a node ID is duplicated,
68
+ * a node embedding does not match the snapshot dimension or contains nonfinite values,
69
+ * or an edge references an unknown node.
69
70
  */
70
71
  static deserialize(snapshot: GraphRAGSnapshot): GraphRAG;
71
72
  clear(): void;
package/dist/graph-rag/index.d.ts.map CHANGED
@@ -1 +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"}
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,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 CHANGED
@@ -33,6 +33,7 @@ let zeroentropy = require("zeroentropy");
33
33
  zeroentropy = __toESM(zeroentropy, 1);
34
34
  let _mastra_core_tools = require("@mastra/core/tools");
35
35
  let _mastra_core_vector = require("@mastra/core/vector");
36
+ let _mastra_core_utils = require("@mastra/core/utils");
36
37
  let _aws_sdk_client_bedrock_agent_runtime = require("@aws-sdk/client-bedrock-agent-runtime");
37
38
  // src/document/prompts/format.ts
38
39
  function format(str, params) {
@@ -4849,6 +4850,7 @@ var RecursiveJsonTransformer = class RecursiveJsonTransformer {
4849
4850
  ensureAscii;
4850
4851
  convertLists;
4851
4852
  constructor({ maxSize = 2e3, ensureAscii = false, convertLists = true }) {
4853
+ if (!Number.isFinite(maxSize) || maxSize < 21) throw new RangeError("JSON maxSize must be at least 21");
4852
4854
  this.maxSize = maxSize;
4853
4855
  this.ensureAscii = ensureAscii;
4854
4856
  this.convertLists = convertLists;
@@ -5781,6 +5783,7 @@ const validationSchemas = {
5781
5783
  disallowedSpecial: setOrAllSchema
5782
5784
  }).strict(),
5783
5785
  json: baseChunkOptionsSchema.extend({
5786
+ maxSize: zod.z.number().min(21).optional(),
5784
5787
  minSize: zod.z.number().positive().optional(),
5785
5788
  ensureAscii: zod.z.boolean().optional(),
5786
5789
  convertLists: zod.z.boolean().optional()
@@ -6210,9 +6213,17 @@ async function executeRerank({ results, query, scorer, options }) {
6210
6213
  ...DEFAULT_WEIGHTS,
6211
6214
  ...options.weights
6212
6215
  };
6216
+ for (const [name, weight] of Object.entries(weights)) if (!Number.isFinite(weight) || weight < 0 || weight > 1) {
6217
+ const err = /* @__PURE__ */ new Error(`Weights must be finite numbers between 0 and 1. Got ${name}: ${weight}`);
6218
+ rerankSpan?.error({
6219
+ error: err,
6220
+ endSpan: true
6221
+ });
6222
+ throw err;
6223
+ }
6213
6224
  const sum = Object.values(weights).reduce((acc, w) => acc.plus(w.toString()), new big_js.Big(0));
6214
6225
  if (!sum.eq(1)) {
6215
- const err = /* @__PURE__ */ new Error(`Weights must add up to 1. Got ${sum} from ${weights}`);
6226
+ const err = /* @__PURE__ */ new Error(`Weights must add up to 1. Got ${sum} from ${JSON.stringify(weights)}`);
6216
6227
  rerankSpan?.error({
6217
6228
  error: err,
6218
6229
  endSpan: true
@@ -6298,12 +6309,17 @@ var GraphRAG = class GraphRAG {
6298
6309
  addNode(node) {
6299
6310
  if (!node.embedding) throw new Error("Node must have an embedding");
6300
6311
  if (node.embedding.length !== this.dimension) throw new Error(`Embedding dimension must be ${this.dimension}`);
6301
- this.nodes.set(node.id, node);
6312
+ for (const component of node.embedding) if (!Number.isFinite(component)) throw new Error("Embedding must contain only finite numbers");
6313
+ this.nodes.set(node.id, {
6314
+ ...node,
6315
+ embedding: [...node.embedding]
6316
+ });
6302
6317
  }
6303
6318
  addEdge(edge) {
6304
6319
  if (!this.nodes.has(edge.source) || !this.nodes.has(edge.target)) throw new Error("Both source and target nodes must exist");
6320
+ if (!Number.isFinite(edge.weight)) throw new Error("Edge weight must be a finite number");
6305
6321
  this.edges.push(edge);
6306
- this.edges.push({
6322
+ if (edge.source !== edge.target) this.edges.push({
6307
6323
  source: edge.target,
6308
6324
  target: edge.source,
6309
6325
  weight: edge.weight,
@@ -6311,7 +6327,10 @@ var GraphRAG = class GraphRAG {
6311
6327
  });
6312
6328
  }
6313
6329
  getNodes() {
6314
- return Array.from(this.nodes.values());
6330
+ return Array.from(this.nodes.values(), (node) => ({
6331
+ ...node,
6332
+ ...node.embedding ? { embedding: [...node.embedding] } : {}
6333
+ }));
6315
6334
  }
6316
6335
  getEdges() {
6317
6336
  return this.edges;
@@ -6344,20 +6363,25 @@ var GraphRAG = class GraphRAG {
6344
6363
  /**
6345
6364
  * Rebuild a GraphRAG instance from a snapshot produced by `serialize()`.
6346
6365
  *
6347
- * @throws if the snapshot version is unsupported, a node embedding does not
6348
- * match the snapshot dimension, or an edge references an unknown node.
6366
+ * @throws if the snapshot version is unsupported, a node ID is duplicated,
6367
+ * a node embedding does not match the snapshot dimension or contains nonfinite values,
6368
+ * or an edge references an unknown node.
6349
6369
  */
6350
6370
  static deserialize(snapshot) {
6351
6371
  if (snapshot?.version !== GRAPH_RAG_SNAPSHOT_VERSION) throw new Error(`Unsupported GraphRAG snapshot version: ${snapshot?.version}`);
6352
6372
  const graph = new GraphRAG(snapshot.dimension, snapshot.threshold);
6353
- for (const node of snapshot.nodes ?? []) graph.addNode({
6354
- ...node,
6355
- ...node.embedding ? { embedding: [...node.embedding] } : {},
6356
- ...node.metadata ? { metadata: structuredClone(node.metadata) } : {}
6357
- });
6373
+ for (const node of snapshot.nodes ?? []) {
6374
+ if (graph.nodes.has(node.id)) throw new Error(`Duplicate node id in snapshot: ${node.id}`);
6375
+ graph.addNode({
6376
+ ...node,
6377
+ ...node.embedding ? { embedding: [...node.embedding] } : {},
6378
+ ...node.metadata ? { metadata: structuredClone(node.metadata) } : {}
6379
+ });
6380
+ }
6358
6381
  for (const edge of snapshot.edges ?? []) {
6359
6382
  if (!graph.nodes.has(edge.source)) throw new Error(`Edge references unknown node: ${edge.source}`);
6360
6383
  if (!graph.nodes.has(edge.target)) throw new Error(`Edge references unknown node: ${edge.target}`);
6384
+ if (!Number.isFinite(edge.weight)) throw new Error("Edge weight must be a finite number");
6361
6385
  }
6362
6386
  graph.edges = (snapshot.edges ?? []).map((edge) => ({ ...edge }));
6363
6387
  return graph;
@@ -6399,22 +6423,21 @@ var GraphRAG = class GraphRAG {
6399
6423
  createGraph(chunks, embeddings) {
6400
6424
  if (!chunks?.length || !embeddings?.length) throw new Error("Chunks and embeddings arrays must not be empty");
6401
6425
  if (chunks.length !== embeddings.length) throw new Error("Chunks and embeddings must have the same length");
6426
+ const graph = new GraphRAG(this.dimension, this.threshold);
6402
6427
  chunks.forEach((chunk, index) => {
6403
- const node = {
6428
+ graph.addNode({
6404
6429
  id: index.toString(),
6405
6430
  content: chunk.text,
6406
6431
  embedding: embeddings[index]?.vector,
6407
6432
  metadata: { ...chunk.metadata }
6408
- };
6409
- this.addNode(node);
6410
- this.nodes.set(node.id, node);
6433
+ });
6411
6434
  });
6412
6435
  for (let i = 0; i < chunks.length; i++) {
6413
6436
  const firstEmbedding = embeddings[i]?.vector;
6414
6437
  for (let j = i + 1; j < chunks.length; j++) {
6415
6438
  const secondEmbedding = embeddings[j]?.vector;
6416
6439
  const similarity = this.cosineSimilarity(firstEmbedding, secondEmbedding);
6417
- if (similarity > this.threshold) this.addEdge({
6440
+ if (similarity > this.threshold) graph.addEdge({
6418
6441
  source: i.toString(),
6419
6442
  target: j.toString(),
6420
6443
  weight: similarity,
@@ -6422,6 +6445,8 @@ var GraphRAG = class GraphRAG {
6422
6445
  });
6423
6446
  }
6424
6447
  }
6448
+ this.nodes = graph.nodes;
6449
+ this.edges = graph.edges;
6425
6450
  }
6426
6451
  selectWeightedNeighbor(neighbors) {
6427
6452
  const totalWeight = neighbors.reduce((sum, n) => sum + n.weight, 0);
@@ -6465,9 +6490,10 @@ var GraphRAG = class GraphRAG {
6465
6490
  */
6466
6491
  query({ query, topK = 10, randomWalkSteps = 100, restartProb = .15, filter }) {
6467
6492
  if (!query || query.length !== this.dimension) throw new Error(`Query embedding must have dimension ${this.dimension}`);
6468
- if (topK < 1) throw new Error("TopK must be greater than 0");
6469
- if (randomWalkSteps < 1) throw new Error("Random walk steps must be greater than 0");
6470
- if (restartProb <= 0 || restartProb >= 1) throw new Error("Restart probability must be between 0 and 1");
6493
+ for (const component of query) if (!Number.isFinite(component)) throw new Error("Query embedding must contain only finite numbers");
6494
+ if (!Number.isInteger(topK) || topK < 1) throw new Error("TopK must be a positive integer");
6495
+ if (!Number.isInteger(randomWalkSteps) || randomWalkSteps < 1) throw new Error("Random walk steps must be a positive integer");
6496
+ if (!Number.isFinite(restartProb) || restartProb <= 0 || restartProb >= 1) throw new Error("Restart probability must be between 0 and 1");
6471
6497
  const filterEntries = Object.entries(filter ?? {});
6472
6498
  const matchesFilter = (node) => filterEntries.length === 0 ? true : filterEntries.every(([key, value]) => node.metadata?.[key] === value);
6473
6499
  const nodesToSearch = Array.from(this.nodes.values()).filter(matchesFilter);
@@ -6725,7 +6751,8 @@ async function resolveVectorStore(options, context, logger) {
6725
6751
  if (typeof vectorStoreOption === "function") {
6726
6752
  const resolved = await vectorStoreOption({
6727
6753
  requestContext,
6728
- mastra
6754
+ mastra,
6755
+ user: (0, _mastra_core_utils.getRequestUser)(requestContext)
6729
6756
  });
6730
6757
  if (!isValidMastraVector(resolved)) {
6731
6758
  const contextStr = buildContextString(context);
@@ -6829,8 +6856,6 @@ const createGraphRAGTool = (options) => {
6829
6856
  ...defaultGraphOptions,
6830
6857
  ...options.graphOptions || {}
6831
6858
  };
6832
- const graphRag = new GraphRAG(graphOptions.dimension, graphOptions.threshold);
6833
- let isInitialized = false;
6834
6859
  const inputSchema = options.enableFilter ? filterSchema : zod.z.object(baseSchema).passthrough();
6835
6860
  return (0, _mastra_core_tools.createTool)({
6836
6861
  id: toolId,
@@ -6890,38 +6915,40 @@ const createGraphRAGTool = (options) => {
6890
6915
  observabilityContext
6891
6916
  });
6892
6917
  if (logger) logger.debug("vectorQuerySearch returned results", { count: results.length });
6893
- if (!isInitialized) {
6894
- const chunks = results.map((result) => ({
6895
- text: result?.metadata?.text,
6896
- metadata: result.metadata ?? {}
6897
- }));
6898
- const embeddings = results.map((result) => ({ vector: result.vector || [] }));
6899
- if (logger) logger.debug("Initializing graph", {
6900
- chunkCount: chunks.length,
6901
- embeddingCount: embeddings.length
6902
- });
6903
- const buildSpan = parentSpan?.createChildSpan({
6904
- type: _mastra_core_observability.SpanType.GRAPH_ACTION,
6905
- name: "graph build",
6906
- input: { nodeCount: chunks.length },
6907
- attributes: {
6908
- action: "build",
6909
- nodeCount: chunks.length,
6910
- threshold: graphOptions.threshold
6911
- }
6912
- });
6913
- try {
6914
- graphRag.createGraph(chunks, embeddings);
6915
- } catch (err) {
6916
- buildSpan?.error({
6917
- error: err,
6918
- endSpan: true
6919
- });
6920
- throw err;
6918
+ if (results.length === 0) return {
6919
+ relevantContext: [],
6920
+ sources: []
6921
+ };
6922
+ const graphRag = new GraphRAG(graphOptions.dimension, graphOptions.threshold);
6923
+ const chunks = results.map((result) => ({
6924
+ text: result?.metadata?.text,
6925
+ metadata: result.metadata ?? {}
6926
+ }));
6927
+ const embeddings = results.map((result) => ({ vector: result.vector || [] }));
6928
+ if (logger) logger.debug("Initializing graph", {
6929
+ chunkCount: chunks.length,
6930
+ embeddingCount: embeddings.length
6931
+ });
6932
+ const buildSpan = parentSpan?.createChildSpan({
6933
+ type: _mastra_core_observability.SpanType.GRAPH_ACTION,
6934
+ name: "graph build",
6935
+ input: { nodeCount: chunks.length },
6936
+ attributes: {
6937
+ action: "build",
6938
+ nodeCount: chunks.length,
6939
+ threshold: graphOptions.threshold
6921
6940
  }
6922
- buildSpan?.end();
6923
- isInitialized = true;
6924
- } else if (logger) logger.debug("Graph already initialized, skipping graph construction");
6941
+ });
6942
+ try {
6943
+ graphRag.createGraph(chunks, embeddings);
6944
+ } catch (err) {
6945
+ buildSpan?.error({
6946
+ error: err,
6947
+ endSpan: true
6948
+ });
6949
+ throw err;
6950
+ }
6951
+ buildSpan?.end();
6925
6952
  const traverseSpan = parentSpan?.createChildSpan({
6926
6953
  type: _mastra_core_observability.SpanType.GRAPH_ACTION,
6927
6954
  name: "graph traverse",