@mastra/mcp-docs-server 0.0.0-default-storage-virtual-file-20250410035748

package/.docs/raw/rag/overview.mdx

@@ -0,0 +1,85 @@
+---
+title: RAG (Retrieval-Augmented Generation) in Mastra | Mastra Docs
+description: Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
+---
+
+# RAG (Retrieval-Augmented Generation) in Mastra
+
+RAG in Mastra helps you enhance LLM outputs by incorporating relevant context from your own data sources, improving accuracy and grounding responses in real information.
+
+Mastra's RAG system provides:
+
+- Standardized APIs to process and embed documents
+- Support for multiple vector stores
+- Chunking and embedding strategies for optimal retrieval
+- Observability for tracking embedding and retrieval performance
+
+## Example
+
+To implement RAG, you process your documents into chunks, create embeddings, store them in a vector database, and then retrieve relevant context at query time.
+
+```ts showLineNumbers copy
+import { embedMany } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { PgVector } from "@mastra/pg";
+import { MDocument } from "@mastra/rag";
+import { z } from "zod";
+
+// 1. Initialize document
+const doc = MDocument.fromText(`Your document text here...`);
+
+// 2. Create chunks
+const chunks = await doc.chunk({
+  strategy: "recursive",
+  size: 512,
+  overlap: 50,
+});
+
+// 3. Generate embeddings; we need to pass the text of each chunk
+const { embeddings } = await embedMany({
+  values: chunks.map(chunk => chunk.text),
+  model: openai.embedding("text-embedding-3-small"),
+});
+
+// 4. Store in vector database
+const pgVector = new PgVector(process.env.POSTGRES_CONNECTION_STRING);
+await pgVector.upsert({
+  indexName: "embeddings",
+  vectors: embeddings,
+}); // using an index name of 'embeddings'
+
+// 5. Query similar chunks
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: queryVector,
+  topK: 3,
+}); // queryVector is the embedding of the query
+
+console.log("Similar chunks:", results);
+```
+
+This example shows the essentials: initialize a document, create chunks, generate embeddings, store them, and query for similar content.
+
+## Document Processing
+
+The basic building block of RAG is document processing. Documents can be chunked using various strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](./chunking-and-embedding.mdx).
+
+## Vector Storage
+
+Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, and Qdrant. See the [vector database doc](./vector-databases.mdx).
+
+## Observability and Debugging
+
+Mastra's RAG system includes observability features to help you optimize your retrieval pipeline:
+
+- Track embedding generation performance and costs
+- Monitor chunk quality and retrieval relevance
+- Analyze query patterns and cache hit rates
+- Export metrics to your observability platform
+
+See the [OTel Configuration](../reference/observability/otel-config.mdx) page for more details.
+
+## More resources
+
+- [Chain of Thought RAG Example](../../examples/rag/usage/cot-rag.mdx)
+- [All RAG Examples](../../examples/) (including different chunking strategies, embedding models, and vector stores)

package/.docs/raw/rag/retrieval.mdx

@@ -0,0 +1,365 @@
+---
+title: "Retrieval, Semantic Search, Reranking | RAG | Mastra Docs"
+description: Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
+---
+
+import { Tabs } from "nextra/components";
+
+## Retrieval in RAG Systems
+
+After storing embeddings, you need to retrieve relevant chunks to answer user queries. 
+
+Mastra provides flexible retrieval options with support for semantic search, filtering, and re-ranking.
+
+## How Retrieval Works
+
+1. The user's query is converted to an embedding using the same model used for document embeddings
+2. This embedding is compared to stored embeddings using vector similarity
+3. The most similar chunks are retrieved and can be optionally:
+  - Filtered by metadata
+  - Re-ranked for better relevance
+  - Processed through a knowledge graph
+
+## Basic Retrieval
+
+The simplest approach is direct semantic search. This method uses vector similarity to find chunks that are semantically similar to the query:
+
+```ts showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { embed } from "ai";
+import { PgVector } from "@mastra/pg";
+
+// Convert query to embedding
+const { embedding } = await embed({
+  value: "What are the main points in the article?",
+  model: openai.embedding('text-embedding-3-small'),
+});
+
+// Query vector store
+const pgVector = new PgVector(process.env.POSTGRES_CONNECTION_STRING);
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+});
+
+// Display results
+console.log(results);
+```
+
+Results include both the text content and a similarity score:
+
+```ts showLineNumbers copy
+[
+  {
+    text: "Climate change poses significant challenges...",
+    score: 0.89,
+    metadata: { source: "article1.txt" }
+  },
+  {
+    text: "Rising temperatures affect crop yields...",
+    score: 0.82,
+    metadata: { source: "article1.txt" }
+  }
+  // ... more results
+]
+```
+
+For an example of how to use the basic retrieval method, see the [Retrieve Results](../../examples/rag/query/retrieve-results.mdx) example.
+
+## Advanced Retrieval options
+
+### Metadata Filtering
+
+Filter results based on metadata fields to narrow down the search space. This is useful when you have documents from different sources, time periods, or with specific attributes. Mastra provides a unified MongoDB-style query syntax that works across all supported vector stores.
+
+For detailed information about available operators and syntax, see the [Metadata Filters Reference](/docs/reference/rag/metadata-filters).
+
+Basic filtering examples:
+
+```ts showLineNumbers copy
+// Simple equality filter
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    source: "article1.txt"
+  }
+});
+
+// Numeric comparison
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    price: { $gt: 100 }
+  }
+});
+
+// Multiple conditions
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    category: "electronics",
+    price: { $lt: 1000 },
+    inStock: true
+  }
+});
+
+// Array operations
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    tags: { $in: ["sale", "new"] }
+  }
+});
+
+// Logical operators
+const results = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: embedding,
+  topK: 10,
+  filter: {
+    $or: [
+      { category: "electronics" },
+      { category: "accessories" }
+    ],
+    $and: [
+      { price: { $gt: 50 } },
+      { price: { $lt: 200 } }
+    ]
+  }
+});
+``` 
+
+Common use cases for metadata filtering:
+- Filter by document source or type
+- Filter by date ranges
+- Filter by specific categories or tags
+- Filter by numerical ranges (e.g., price, rating)
+- Combine multiple conditions for precise querying
+- Filter by document attributes (e.g., language, author)
+
+For an example of how to use metadata filtering, see the [Hybrid Vector Search](../../examples/rag/query/hybrid-vector-search.mdx) example.
+
+### Vector Query Tool
+
+Sometimes you want to give your agent the ability to query a vector database directly. The Vector Query Tool allows your agent to be in charge of retrieval decisions, combining semantic search with optional filtering and reranking based on the agent's understanding of the user's needs.
+
+```ts showLineNumbers copy
+const vectorQueryTool = createVectorQueryTool({
+  vectorStoreName: 'pgVector',
+  indexName: 'embeddings',
+  model: openai.embedding('text-embedding-3-small'),
+});
+```
+
+When creating the tool, pay special attention to the tool's name and description - these help the agent understand when and how to use the retrieval capabilities. For example, you might name it "SearchKnowledgeBase" and describe it as "Search through our documentation to find relevant information about X topic."
+
+This is particularly useful when:
+- Your agent needs to dynamically decide what information to retrieve
+- The retrieval process requires complex decision-making
+- You want the agent to combine multiple retrieval strategies based on context
+
+For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](/docs/reference/tools/vector-query-tool).
+
+### Vector Store Prompts
+
+Vector store prompts define query patterns and filtering capabilities for each vector database implementation. 
+When implementing filtering, these prompts are required in the agent's instructions to specify valid operators and syntax for each vector store implementation.
+
+<Tabs items={['Pg Vector', 'Pinecone', 'Qdrant', 'Chroma', 'Astra', 'LibSQL', 'Upstash', 'Cloudflare']}>
+  <Tabs.Tab>
+  ```ts showLineNumbers copy
+import { openai } from '@ai-sdk/openai';
+import { PGVECTOR_PROMPT } from "@mastra/rag";
+
+export const ragAgent = new Agent({
+  name: 'RAG Agent',
+  model: openai('gpt-4o-mini'),
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${PGVECTOR_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+import { openai } from '@ai-sdk/openai';
+import { PINECONE_PROMPT } from "@mastra/rag";
+
+export const ragAgent = new Agent({
+  name: 'RAG Agent',
+  model: openai('gpt-4o-mini'),
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${PINECONE_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+import { openai } from '@ai-sdk/openai';
+import { QDRANT_PROMPT } from "@mastra/rag";
+
+export const ragAgent = new Agent({
+  name: 'RAG Agent',
+  model: openai('gpt-4o-mini'),
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${QDRANT_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+import { openai } from '@ai-sdk/openai';
+import { CHROMA_PROMPT } from "@mastra/rag";
+
+export const ragAgent = new Agent({
+  name: 'RAG Agent',
+  model: openai('gpt-4o-mini'),
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${CHROMA_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+import { openai } from '@ai-sdk/openai';
+import { ASTRA_PROMPT } from "@mastra/rag";
+
+export const ragAgent = new Agent({
+  name: 'RAG Agent',
+  model: openai('gpt-4o-mini'),
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${ASTRA_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+import { openai } from '@ai-sdk/openai';
+import { LIBSQL_PROMPT } from "@mastra/rag";
+
+export const ragAgent = new Agent({
+  name: 'RAG Agent',
+  model: openai('gpt-4o-mini'),
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${LIBSQL_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+import { openai } from '@ai-sdk/openai';
+import { UPSTASH_PROMPT } from "@mastra/rag";
+
+export const ragAgent = new Agent({
+  name: 'RAG Agent',
+  model: openai('gpt-4o-mini'),
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${UPSTASH_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+</Tabs.Tab>
+<Tabs.Tab>
+  ```ts filename="vector-store.ts" showLineNumbers copy
+import { openai } from '@ai-sdk/openai';
+import { VECTORIZE_PROMPT } from "@mastra/rag";
+
+export const ragAgent = new Agent({
+  name: 'RAG Agent',
+  model: openai('gpt-4o-mini'),
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${VECTORIZE_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+});
+```
+</Tabs.Tab>
+</Tabs>
+
+### Re-ranking
+
+Initial vector similarity search can sometimes miss nuanced relevance. Re-ranking is a more computationally expensive process, but more accurate algorithm that improves results by:
+
+- Considering word order and exact matches
+- Applying more sophisticated relevance scoring
+- Using a method called cross-attention between query and documents
+
+Here's how to use re-ranking:
+
+```ts showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { rerank } from "@mastra/rag";
+
+// Get initial results from vector search
+const initialResults = await pgVector.query({
+  indexName: "embeddings",
+  queryVector: queryEmbedding,
+  topK: 10,
+});
+
+// Re-rank the results
+const rerankedResults = await rerank(initialResults, query, openai('gpt-4o-mini'));
+```
+
+> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
+
+The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.
+
+For more details about re-ranking, see the [rerank()](/docs/reference/rag/rerank) method.
+
+For an example of how to use the re-ranking method, see the [Re-ranking Results](../../examples/rag/rerank/rerank.mdx) example.
+
+### Graph-based Retrieval
+
+For documents with complex relationships, graph-based retrieval can follow connections between chunks. This helps when:
+
+- Information is spread across multiple documents
+- Documents reference each other
+- You need to traverse relationships to find complete answers
+
+Example setup:
+
+```ts showLineNumbers copy
+const graphQueryTool = createGraphQueryTool({
+  vectorStoreName: 'pgVector',
+  indexName: 'embeddings',
+  model: openai.embedding('text-embedding-3-small'),
+  graphOptions: {
+    threshold: 0.7,
+  }
+});
+```
+
+For more details about graph-based retrieval, see the [GraphRAG](/docs/reference/rag/graph-rag) class and the [createGraphQueryTool()](/docs/reference/tools/graph-rag-tool) function.
+
+For an example of how to use the graph-based retrieval method, see the [Graph-based Retrieval](../../examples/rag/usage/graph-rag.mdx) example.