@mastra/rag 2.1.2 → 2.1.3-alpha.0

package/dist/docs/references/reference-rag-extract-params.md

@@ -28,65 +28,65 @@ const chunks = await doc.chunk({
 
 The `extract` parameter accepts the following fields:
 
-**title?:** (`boolean | TitleExtractorsArgs`): Enable title extraction. Set to true for default settings, or provide custom configuration.
+**title** (`boolean | TitleExtractorsArgs`): Enable title extraction. Set to true for default settings, or provide custom configuration.
 
-**summary?:** (`boolean | SummaryExtractArgs`): Enable summary extraction. Set to true for default settings, or provide custom configuration.
+**summary** (`boolean | SummaryExtractArgs`): Enable summary extraction. Set to true for default settings, or provide custom configuration.
 
-**questions?:** (`boolean | QuestionAnswerExtractArgs`): Enable question generation. Set to true for default settings, or provide custom configuration.
+**questions** (`boolean | QuestionAnswerExtractArgs`): Enable question generation. Set to true for default settings, or provide custom configuration.
 
-**keywords?:** (`boolean | KeywordExtractArgs`): Enable keyword extraction. Set to true for default settings, or provide custom configuration.
+**keywords** (`boolean | KeywordExtractArgs`): Enable keyword extraction. Set to true for default settings, or provide custom configuration.
 
-**schema?:** (`SchemaExtractArgs`): Enable structured metadata extraction using a Zod schema.
+**schema** (`SchemaExtractArgs`): Enable structured metadata extraction using a Zod schema.
 
-## Extractor Arguments
+## Extractor arguments
 
-### TitleExtractorsArgs
+### `TitleExtractorsArgs`
 
-**llm?:** (`MastraLanguageModel`): AI SDK language model to use for title extraction
+**llm** (`MastraLanguageModel`): AI SDK language model to use for title extraction
 
-**nodes?:** (`number`): Number of title nodes to extract
+**nodes** (`number`): Number of title nodes to extract
 
-**nodeTemplate?:** (`string`): Custom prompt template for title node extraction. Must include {context} placeholder
+**nodeTemplate** (`string`): Custom prompt template for title node extraction. Must include {context} placeholder
 
-**combineTemplate?:** (`string`): Custom prompt template for combining titles. Must include {context} placeholder
+**combineTemplate** (`string`): Custom prompt template for combining titles. Must include {context} placeholder
 
-### SummaryExtractArgs
+### `SummaryExtractArgs`
 
-**llm?:** (`MastraLanguageModel`): AI SDK language model to use for summary extraction
+**llm** (`MastraLanguageModel`): AI SDK language model to use for summary extraction
 
-**summaries?:** (`('self' | 'prev' | 'next')[]`): List of summary types to generate. Can only include 'self' (current chunk), 'prev' (previous chunk), or 'next' (next chunk)
+**summaries** (`('self' | 'prev' | 'next')[]`): List of summary types to generate. Can only include 'self' (current chunk), 'prev' (previous chunk), or 'next' (next chunk)
 
-**promptTemplate?:** (`string`): Custom prompt template for summary generation. Must include {context} placeholder
+**promptTemplate** (`string`): Custom prompt template for summary generation. Must include {context} placeholder
 
-### QuestionAnswerExtractArgs
+### `QuestionAnswerExtractArgs`
 
-**llm?:** (`MastraLanguageModel`): AI SDK language model to use for question generation
+**llm** (`MastraLanguageModel`): AI SDK language model to use for question generation
 
-**questions?:** (`number`): Number of questions to generate
+**questions** (`number`): Number of questions to generate
 
-**promptTemplate?:** (`string`): Custom prompt template for question generation. Must include both {context} and {numQuestions} placeholders
+**promptTemplate** (`string`): Custom prompt template for question generation. Must include both {context} and {numQuestions} placeholders
 
-**embeddingOnly?:** (`boolean`): If true, only generate embeddings without actual questions
+**embeddingOnly** (`boolean`): If true, only generate embeddings without actual questions
 
-### KeywordExtractArgs
+### `KeywordExtractArgs`
 
-**llm?:** (`MastraLanguageModel`): AI SDK language model to use for keyword extraction
+**llm** (`MastraLanguageModel`): AI SDK language model to use for keyword extraction
 
-**keywords?:** (`number`): Number of keywords to extract
+**keywords** (`number`): Number of keywords to extract
 
-**promptTemplate?:** (`string`): Custom prompt template for keyword extraction. Must include both {context} and {maxKeywords} placeholders
+**promptTemplate** (`string`): Custom prompt template for keyword extraction. Must include both {context} and {maxKeywords} placeholders
 
-### SchemaExtractArgs
+### `SchemaExtractArgs`
 
-**schema:** (`ZodType`): Zod schema defining the structure of the data to extract.
+**schema** (`ZodType`): Zod schema defining the structure of the data to extract.
 
-**llm?:** (`MastraLanguageModel`): AI SDK language model to use for extraction.
+**llm** (`MastraLanguageModel`): AI SDK language model to use for extraction.
 
-**instructions?:** (`string`): Instructions for the LLM on what to extract.
+**instructions** (`string`): Instructions for the LLM on what to extract.
 
-**metadataKey?:** (`string`): Key to nest extraction results under. If omitted, results are spread into the metadata object.
+**metadataKey** (`string`): Key to nest extraction results under. If omitted, results are spread into the metadata object.
 
-## Advanced Example
+## Advanced example
 
 ```typescript
 import { MDocument } from '@mastra/rag'
@@ -145,7 +145,7 @@ const chunks = await doc.chunk({
 // }
 ```
 
-## Document Grouping for Title Extraction
+## Document grouping for title extraction
 
 When using the `TitleExtractor`, you can group multiple chunks together for title extraction by specifying a shared `docId` in the `metadata` field of each chunk. All chunks with the same `docId` will receive the same extracted title. If no `docId` is set, each chunk is treated as its own document for title extraction.
 

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

@@ -2,7 +2,7 @@
 
 The `GraphRAG` class implements a graph-based approach to retrieval augmented generation. It creates a knowledge graph from document chunks where nodes represent documents and edges represent semantic relationships, enabling both direct similarity matching and discovery of related content through graph traversal.
 
-## Basic Usage
+## Basic usage
 
 ```typescript
 import { GraphRAG } from '@mastra/rag'
@@ -24,15 +24,15 @@ const results = await graphRag.query({
 })
 ```
 
-## Constructor Parameters
+## Constructor parameters
 
-**dimension?:** (`number`): Dimension of the embedding vectors (Default: `1536`)
+**dimension** (`number`): Dimension of the embedding vectors (Default: `1536`)
 
-**threshold?:** (`number`): Similarity threshold for creating edges between nodes (0-1) (Default: `0.7`)
+**threshold** (`number`): Similarity threshold for creating edges between nodes (0-1) (Default: `0.7`)
 
 ## Methods
 
-### createGraph
+### `createGraph`
 
 Creates a knowledge graph from document chunks and their embeddings.
 
@@ -42,9 +42,9 @@ createGraph(chunks: GraphChunk[], embeddings: GraphEmbedding[]): void
 
 #### Parameters
 
-**chunks:** (`GraphChunk[]`): Array of document chunks with text and metadata
+**chunks** (`GraphChunk[]`): Array of document chunks with text and metadata
 
-**embeddings:** (`GraphEmbedding[]`): Array of embeddings corresponding to chunks
+**embeddings** (`GraphEmbedding[]`): Array of embeddings corresponding to chunks
 
 ### query
 
@@ -66,27 +66,27 @@ query({
 
 #### Parameters
 
-**query:** (`number[]`): Query embedding vector
+**query** (`number[]`): Query embedding vector
 
-**topK?:** (`number`): Number of results to return (Default: `10`)
+**topK** (`number`): Number of results to return (Default: `10`)
 
-**randomWalkSteps?:** (`number`): Number of steps in random walk (Default: `100`)
+**randomWalkSteps** (`number`): Number of steps in random walk (Default: `100`)
 
-**restartProb?:** (`number`): Probability of restarting walk from query node (Default: `0.15`)
+**restartProb** (`number`): Probability of restarting walk from query node (Default: `0.15`)
 
 #### Returns
 
 Returns an array of `RankedNode` objects, where each node contains:
 
-**id:** (`string`): Unique identifier for the node
+**id** (`string`): Unique identifier for the node
 
-**content:** (`string`): Text content of the document chunk
+**content** (`string`): Text content of the document chunk
 
-**metadata:** (`Record<string, any>`): Additional metadata associated with the chunk
+**metadata** (`Record<string, any>`): Additional metadata associated with the chunk
 
-**score:** (`number`): Combined relevance score from graph traversal
+**score** (`number`): Combined relevance score from graph traversal
 
-## Advanced Example
+## Advanced example
 
 ```typescript
 const graphRag = new GraphRAG({

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

@@ -11,12 +11,12 @@ function rerank(
 ): Promise<RerankResult[]>
 ```
 
-## Usage Example
+## Usage example
 
 ```typescript
 import { rerank } from '@mastra/rag'
 
-const model = 'openai/gpt-5.1'
+const model = 'openai/gpt-5.4'
 
 const rerankedResults = await rerank(vectorSearchResults, 'How do I deploy to production?', model, {
   weights: {
@@ -30,45 +30,53 @@ const rerankedResults = await rerank(vectorSearchResults, 'How do I deploy to pr
 
 ## Parameters
 
-**results:** (`QueryResult[]`): The vector search results to rerank
+**results** (`QueryResult[]`): The vector search results to rerank
 
-**query:** (`string`): The search query text used to evaluate relevance
+**query** (`string`): The search query text used to evaluate relevance
 
-**model:** (`MastraLanguageModel`): The language Model to use for reranking
+**model** (`MastraLanguageModel`): The language Model to use for reranking
 
-**options?:** (`RerankerFunctionOptions`): Options for the reranking model
+**options** (`RerankerFunctionOptions`): Options for the reranking model
 
-The rerank function accepts any LanguageModel from the Vercel AI SDK. When using the Cohere model `rerank-v3.5`, it will automatically use Cohere's reranking capabilities.
+**options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1)
 
-> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
+**options.weights.semantic** (`number (default: 0.4)`): Weight for semantic relevance
+
+**options.weights.vector** (`number (default: 0.4)`): Weight for vector similarity
+
+**options.weights.position** (`number (default: 0.2)`): Weight for position-based scoring
 
-### RerankerFunctionOptions
+**options.queryEmbedding** (`number[]`): Embedding of the query
 
-**weights?:** (`WeightConfig`): numbersemantic?:number (default: 0.4)Weight for semantic relevancenumbervector?:number (default: 0.4)Weight for vector similaritynumberposition?:number (default: 0.2)Weight for position-based scoring
+**options.topK** (`number`): Number of top results to return
 
-**queryEmbedding?:** (`number[]`): Embedding of the query
+The rerank function accepts any LanguageModel from the Vercel AI SDK. When using the Cohere model `rerank-v3.5`, it will automatically use Cohere's reranking capabilities.
 
-**topK?:** (`number`): Number of top results to return (Default: `3`)
+> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
 
 ## Returns
 
 The function returns an array of `RerankResult` objects:
 
-**result:** (`QueryResult`): The original query result
+**result** (`QueryResult`): The original query result
+
+**score** (`number`): Combined reranking score (0-1)
+
+**details** (`ScoringDetails`): Detailed scoring information
 
-**score:** (`number`): Combined reranking score (0-1)
+### `ScoringDetails`
 
-**details:** (`ScoringDetails`): Detailed scoring information
+**semantic** (`number`): Semantic relevance score (0-1)
 
-### ScoringDetails
+**vector** (`number`): Vector similarity score (0-1)
 
-**semantic:** (`number`): Semantic relevance score (0-1)
+**position** (`number`): Position-based score (0-1)
 
-**vector:** (`number`): Vector similarity score (0-1)
+**queryAnalysis** (`object`): Query analysis details
 
-**position:** (`number`): Position-based score (0-1)
+**queryAnalysis.magnitude**: Magnitude of the query
 
-**queryAnalysis?:** (`object`): numbermagnitude:Magnitude of the querynumber\[]dominantFeatures:Dominant features of the query
+**queryAnalysis.dominantFeatures**: Dominant features of the query
 
 ## Related
 

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

@@ -11,7 +11,7 @@ function rerankWithScorer({
 }): Promise<RerankResult[]>;
 ```
 
-## Usage Example
+## Usage example
 
 ```typescript
 import { rerankWithScorer as rerank, CohereRelevanceScorer } from '@mastra/rag'
@@ -35,45 +35,53 @@ const rerankedResults = await rerank({
 
 ## Parameters
 
-**results:** (`QueryResult[]`): The vector search results to rerank
+**results** (`QueryResult[]`): The vector search results to rerank
 
-**query:** (`string`): The search query text used to evaluate relevance
+**query** (`string`): The search query text used to evaluate relevance
 
-**scorer:** (`RelevanceScoreProvider`): The relevance scorer to use for reranking
+**scorer** (`RelevanceScoreProvider`): The relevance scorer to use for reranking
 
-**options?:** (`RerankerFunctionOptions`): Options for the reranking model
+**options** (`RerankerFunctionOptions`): Options for the reranking model
 
-The `rerankWithScorer` function accepts any `RelevanceScoreProvider` from @mastra/rag.
+**options.weights** (`WeightConfig`): Weights for different scoring components (must add up to 1)
 
-> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
+**options.weights.semantic** (`number (default: 0.4)`): Weight for semantic relevance
+
+**options.weights.vector** (`number (default: 0.4)`): Weight for vector similarity
+
+**options.weights.position** (`number (default: 0.2)`): Weight for position-based scoring
 
-### RerankerFunctionOptions
+**options.queryEmbedding** (`number[]`): Embedding of the query
 
-**weights?:** (`WeightConfig`): numbersemantic?:number (default: 0.4)Weight for semantic relevancenumbervector?:number (default: 0.4)Weight for vector similaritynumberposition?:number (default: 0.2)Weight for position-based scoring
+**options.topK** (`number`): Number of top results to return
 
-**queryEmbedding?:** (`number[]`): Embedding of the query
+The `rerankWithScorer` function accepts any `RelevanceScoreProvider` from @mastra/rag.
 
-**topK?:** (`number`): Number of top results to return (Default: `3`)
+> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
 
 ## Returns
 
 The function returns an array of `RerankResult` objects:
 
-**result:** (`QueryResult`): The original query result
+**result** (`QueryResult`): The original query result
+
+**score** (`number`): Combined reranking score (0-1)
+
+**details** (`ScoringDetails`): Detailed scoring information
 
-**score:** (`number`): Combined reranking score (0-1)
+### `ScoringDetails`
 
-**details:** (`ScoringDetails`): Detailed scoring information
+**semantic** (`number`): Semantic relevance score (0-1)
 
-### ScoringDetails
+**vector** (`number`): Vector similarity score (0-1)
 
-**semantic:** (`number`): Semantic relevance score (0-1)
+**position** (`number`): Position-based score (0-1)
 
-**vector:** (`number`): Vector similarity score (0-1)
+**queryAnalysis** (`object`): Query analysis details
 
-**position:** (`number`): Position-based score (0-1)
+**queryAnalysis.magnitude**: Magnitude of the query
 
-**queryAnalysis?:** (`object`): numbermagnitude:Magnitude of the querynumber\[]dominantFeatures:Dominant features of the query
+**queryAnalysis.dominantFeatures**: Dominant features of the query
 
 ## Related
 

package/dist/docs/references/reference-tools-document-chunker-tool.md

@@ -2,7 +2,7 @@
 
 The `createDocumentChunkerTool()` function creates a tool for splitting documents into smaller chunks for efficient processing and retrieval. It supports different chunking strategies and configurable parameters.
 
-## Basic Usage
+## Basic usage
 
 ```typescript
 import { createDocumentChunkerTool, MDocument } from '@mastra/rag'
@@ -27,25 +27,25 @@ const { chunks } = await chunker.execute()
 
 ## Parameters
 
-**doc:** (`MDocument`): The document to be chunked
+**doc** (`MDocument`): The document to be chunked
 
-**params?:** (`ChunkParams`): Configuration parameters for chunking (Default: `Default chunking parameters`)
+**params** (`ChunkParams`): Configuration parameters for chunking (Default: `Default chunking parameters`)
 
-### ChunkParams
+### `ChunkParams`
 
-**strategy?:** (`'recursive'`): The chunking strategy to use (Default: `'recursive'`)
+**strategy** (`'recursive'`): The chunking strategy to use (Default: `'recursive'`)
 
-**size?:** (`number`): Target size of each chunk in tokens/characters (Default: `512`)
+**size** (`number`): Target size of each chunk in tokens/characters (Default: `512`)
 
-**overlap?:** (`number`): Number of overlapping tokens/characters between chunks (Default: `50`)
+**overlap** (`number`): Number of overlapping tokens/characters between chunks (Default: `50`)
 
-**separator?:** (`string`): Character(s) to use as chunk separator (Default: `'\n'`)
+**separator** (`string`): Character(s) to use as chunk separator (Default: `'\n'`)
 
 ## Returns
 
-**chunks:** (`DocumentChunk[]`): Array of document chunks with their content and metadata
+**chunks** (`DocumentChunk[]`): Array of document chunks with their content and metadata
 
-## Example with Custom Parameters
+## Example with custom parameters
 
 ```typescript
 const technicalDoc = new MDocument({
@@ -74,7 +74,7 @@ chunks.forEach((chunk, index) => {
 })
 ```
 
-## Tool Details
+## Tool details
 
 The chunker is created as a Mastra tool with the following properties:
 

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

@@ -2,7 +2,7 @@
 
 The `createGraphRAGTool()` creates a tool that enhances RAG by building a graph of semantic relationships between documents. It uses the `GraphRAG` system under the hood to provide graph-based retrieval, finding relevant content through both direct similarity and connected relationships.
 
-## Usage Example
+## Usage example
 
 ```typescript
 import { createGraphRAGTool } from '@mastra/rag'
@@ -25,45 +25,43 @@ const graphTool = createGraphRAGTool({
 
 > **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `model`, `id`, and `description` can only be set at creation time.
 
-**id?:** (`string`): Custom ID for the tool. By default: 'GraphRAG {vectorStoreName} {indexName} Tool'. (Set at creation only.)
+**id** (`string`): Custom ID for the tool. By default: 'GraphRAG {vectorStoreName} {indexName} Tool'. (Set at creation only.)
 
-**description?:** (`string`): Custom description for the tool. By default: 'Access and analyze relationships between information in the knowledge base to answer complex questions about connections and patterns.' (Set at creation only.)
+**description** (`string`): Custom description for the tool. By default: 'Access and analyze relationships between information in the knowledge base to answer complex questions about connections and patterns.' (Set at creation only.)
 
-**vectorStoreName:** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
+**vectorStoreName** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
 
-**indexName:** (`string`): Name of the index within the vector store. (Can be set at creation or overridden at runtime.)
+**indexName** (`string`): Name of the index within the vector store. (Can be set at creation or overridden at runtime.)
 
-**model:** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
+**model** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
 
-**enableFilter?:** (`boolean`): Enable filtering of results based on metadata. (Set at creation only, but will be automatically enabled if a filter is provided in the request context.) (Default: `false`)
+**enableFilter** (`boolean`): Enable filtering of results based on metadata. (Set at creation only, but will be automatically enabled if a filter is provided in the request context.) (Default: `false`)
 
-**includeSources?:** (`boolean`): Include the full retrieval objects in the results. (Can be set at creation or overridden at runtime.) (Default: `true`)
+**includeSources** (`boolean`): Include the full retrieval objects in the results. (Can be set at creation or overridden at runtime.) (Default: `true`)
 
-**graphOptions?:** (`GraphOptions`): Configuration for the graph-based retrieval (Default: `Default graph options`)
+**graphOptions** (`GraphOptions`): Configuration for the graph-based retrieval (Default: `Default graph options`)
 
-**providerOptions?:** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
+**graphOptions.dimension** (`number`): Dimension of the embedding vectors
 
-**vectorStore?:** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, \`vectorStoreName\` becomes optional.
+**graphOptions.threshold** (`number`): Similarity threshold for creating edges between nodes (0-1)
 
-### GraphOptions
+**graphOptions.randomWalkSteps** (`number`): Number of steps in random walk for graph traversal. (Can be set at creation or overridden at runtime.)
 
-**dimension?:** (`number`): Dimension of the embedding vectors (Default: `1536`)
+**graphOptions.restartProb** (`number`): Probability of restarting random walk from query node. (Can be set at creation or overridden at runtime.)
 
-**threshold?:** (`number`): Similarity threshold for creating edges between nodes (0-1) (Default: `0.7`)
+**providerOptions** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
 
-**randomWalkSteps?:** (`number`): Number of steps in random walk for graph traversal. (Can be set at creation or overridden at runtime.) (Default: `100`)
-
-**restartProb?:** (`number`): Probability of restarting random walk from query node. (Can be set at creation or overridden at runtime.) (Default: `0.15`)
+**vectorStore** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, \`vectorStoreName\` becomes optional.
 
 ## Returns
 
 The tool returns an object with:
 
-**relevantContext:** (`string`): Combined text from the most relevant document chunks, retrieved using graph-based ranking
+**relevantContext** (`string`): Combined text from the most relevant document chunks, retrieved using graph-based ranking
 
-**sources:** (`QueryResult[]`): Array of full retrieval result objects. Each object contains all information needed to reference the original document, chunk, and similarity score.
+**sources** (`QueryResult[]`): Array of full retrieval result objects. Each object contains all information needed to reference the original document, chunk, and similarity score.
 
-### QueryResult object structure
+### `QueryResult` object structure
 
 ```typescript
 {
@@ -75,7 +73,7 @@ The tool returns an object with:
 }
 ```
 
-## Default Tool Description
+## Default tool description
 
 The default description focuses on:
 
@@ -83,7 +81,7 @@ The default description focuses on:
 - Finding patterns and connections
 - Answering complex queries
 
-## Advanced Example
+## Advanced example
 
 ```typescript
 const graphTool = createGraphRAGTool({
@@ -99,7 +97,7 @@ const graphTool = createGraphRAGTool({
 })
 ```
 
-## Example with Custom Description
+## Example with custom description
 
 ```typescript
 const graphTool = createGraphRAGTool({
@@ -113,7 +111,7 @@ const graphTool = createGraphRAGTool({
 
 This example shows how to customize the tool description for a specific use case while maintaining its core purpose of relationship analysis.
 
-## Example: Using Request Context
+## Example: Using request context
 
 ```typescript
 const graphTool = createGraphRAGTool({
@@ -149,7 +147,7 @@ For more information on request context, please see:
 - [Agent Request Context](https://mastra.ai/docs/server/request-context)
 - [Request Context](https://mastra.ai/docs/server/request-context)
 
-## Dynamic Vector Store for Multi-Tenant Applications
+## Dynamic vector store for multi-tenant applications
 
 For multi-tenant applications where each tenant has isolated data, you can pass a resolver function instead of a static vector store: