@mastra/libsql 0.0.0-workflow-timeout-issue-20260220185702 → 0.0.0-workflow-graph-crash-20260527191009

package/dist/docs/references/docs-rag-retrieval.md

@@ -1,10 +1,10 @@
-# Retrieval in RAG Systems
+# 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
+## 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
@@ -14,34 +14,34 @@ Mastra provides flexible retrieval options with support for semantic search, fil
 - Re-ranked for better relevance
 - Processed through a knowledge graph
 
-## Basic Retrieval
+## 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
-import { embed } from "ai";
-import { PgVector } from "@mastra/pg";
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+import { embed } from 'ai'
+import { PgVector } from '@mastra/pg'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 // Convert query to embedding
 const { embedding } = await embed({
-  value: "What are the main points in the article?",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-});
+  value: 'What are the main points in the article?',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+})
 
 // Query vector store
 const pgVector = new PgVector({
   id: 'pg-vector',
   connectionString: process.env.POSTGRES_CONNECTION_STRING,
-});
+})
 const results = await pgVector.query({
-  indexName: "embeddings",
+  indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
-});
+})
 
 // Display results
-console.log(results);
+console.log(results)
 ```
 
 The `topK` parameter specifies the maximum number of most similar results to return from the vector search.
@@ -51,19 +51,19 @@ Results include both the text content and a similarity score:
 ```ts
 [
   {
-    text: "Climate change poses significant challenges...",
+    text: 'Climate change poses significant challenges...',
     score: 0.89,
-    metadata: { source: "article1.txt" },
+    metadata: { source: 'article1.txt' },
   },
   {
-    text: "Rising temperatures affect crop yields...",
+    text: 'Rising temperatures affect crop yields...',
     score: 0.82,
-    metadata: { source: "article1.txt" },
+    metadata: { source: 'article1.txt' },
   },
-];
+]
 ```
 
-## Advanced Retrieval options
+## Advanced retrieval options
 
 ### Metadata Filtering
 
@@ -78,56 +78,56 @@ Basic filtering examples:
 ```ts
 // Simple equality filter
 const results = await pgVector.query({
-  indexName: "embeddings",
+  indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
   filter: {
-    source: "article1.txt",
+    source: 'article1.txt',
   },
-});
+})
 
 // Numeric comparison
 const results = await pgVector.query({
-  indexName: "embeddings",
+  indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
   filter: {
     price: { $gt: 100 },
   },
-});
+})
 
 // Multiple conditions
 const results = await pgVector.query({
-  indexName: "embeddings",
+  indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
   filter: {
-    category: "electronics",
+    category: 'electronics',
     price: { $lt: 1000 },
     inStock: true,
   },
-});
+})
 
 // Array operations
 const results = await pgVector.query({
-  indexName: "embeddings",
+  indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
   filter: {
-    tags: { $in: ["sale", "new"] },
+    tags: { $in: ['sale', 'new'] },
   },
-});
+})
 
 // Logical operators
 const results = await pgVector.query({
-  indexName: "embeddings",
+  indexName: 'embeddings',
   queryVector: embedding,
   topK: 10,
   filter: {
-    $or: [{ category: "electronics" }, { category: "accessories" }],
+    $or: [{ category: 'electronics' }, { category: 'accessories' }],
     $and: [{ price: { $gt: 50 } }, { price: { $lt: 200 } }],
   },
-});
+})
 ```
 
 Common use cases for metadata filtering:
@@ -144,14 +144,14 @@ Common use cases for metadata filtering:
 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
-import { createVectorQueryTool } from "@mastra/rag";
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+import { createVectorQueryTool } from '@mastra/rag'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const vectorQueryTool = createVectorQueryTool({
-  vectorStoreName: "pgVector",
-  indexName: "embeddings",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-});
+  vectorStoreName: 'pgVector',
+  indexName: 'embeddings',
+  model: new ModelRouterEmbeddingModel('openai/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."
@@ -171,26 +171,26 @@ The Vector Query Tool supports database-specific configurations that enable you
 > Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ url: '...' })`).
 
 ```ts
-import { createVectorQueryTool } from "@mastra/rag";
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+import { createVectorQueryTool } from '@mastra/rag'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 // Pinecone with namespace
 const pineconeQueryTool = createVectorQueryTool({
-  vectorStoreName: "pinecone",
-  indexName: "docs",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  vectorStoreName: 'pinecone',
+  indexName: 'docs',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   databaseConfig: {
     pinecone: {
-      namespace: "production", // Isolate data by environment
+      namespace: 'production', // Isolate data by environment
     },
   },
-});
+})
 
 // pgVector with performance tuning
 const pgVectorQueryTool = createVectorQueryTool({
-  vectorStoreName: "postgres",
-  indexName: "embeddings",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  vectorStoreName: 'postgres',
+  indexName: 'embeddings',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   databaseConfig: {
     pgvector: {
       minScore: 0.7, // Filter low-quality results
@@ -198,33 +198,33 @@ const pgVectorQueryTool = createVectorQueryTool({
       probes: 10, // IVFFlat probe parameter
     },
   },
-});
+})
 
 // Chroma with advanced filtering
 const chromaQueryTool = createVectorQueryTool({
-  vectorStoreName: "chroma",
-  indexName: "documents",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  vectorStoreName: 'chroma',
+  indexName: 'documents',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   databaseConfig: {
     chroma: {
-      where: { category: "technical" },
-      whereDocument: { $contains: "API" },
+      where: { category: 'technical' },
+      whereDocument: { $contains: 'API' },
     },
   },
-});
+})
 
 // LanceDB with table specificity
 const lanceQueryTool = createVectorQueryTool({
-  vectorStoreName: "lance",
-  indexName: "documents",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  vectorStoreName: 'lance',
+  indexName: 'documents',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   databaseConfig: {
     lance: {
-      tableName: "myVectors", // Specify which table to query
+      tableName: 'myVectors', // Specify which table to query
       includeAllColumns: true, // Include all metadata columns in results
     },
   },
-});
+})
 ```
 
 **Key Benefits:**
@@ -246,19 +246,16 @@ const lanceQueryTool = createVectorQueryTool({
 You can also override these configurations at runtime using the request context:
 
 ```ts
-import { RequestContext } from "@mastra/core/request-context";
+import { RequestContext } from '@mastra/core/request-context'
 
-const requestContext = new RequestContext();
-requestContext.set("databaseConfig", {
+const requestContext = new RequestContext()
+requestContext.set('databaseConfig', {
   pinecone: {
-    namespace: "runtime-namespace",
+    namespace: 'runtime-namespace',
   },
-});
+})
 
-await pineconeQueryTool.execute(
-  { queryText: "search query" },
-  { mastra, requestContext }
-);
+await pineconeQueryTool.execute({ queryText: 'search query' }, { mastra, requestContext })
 ```
 
 For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](https://mastra.ai/reference/tools/vector-query-tool).
@@ -270,188 +267,188 @@ Vector store prompts define query patterns and filtering capabilities for each v
 **pgVector**:
 
 ```ts
-import { PGVECTOR_PROMPT } from "@mastra/pg";
+import { PGVECTOR_PROMPT } from '@mastra/pg'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${PGVECTOR_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **Pinecone**:
 
 ```ts
-import { PINECONE_PROMPT } from "@mastra/pinecone";
+import { PINECONE_PROMPT } from '@mastra/pinecone'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${PINECONE_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **Qdrant**:
 
 ```ts
-import { QDRANT_PROMPT } from "@mastra/qdrant";
+import { QDRANT_PROMPT } from '@mastra/qdrant'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${QDRANT_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **Chroma**:
 
 ```ts
-import { CHROMA_PROMPT } from "@mastra/chroma";
+import { CHROMA_PROMPT } from '@mastra/chroma'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${CHROMA_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **Astra**:
 
 ```ts
-import { ASTRA_PROMPT } from "@mastra/astra";
+import { ASTRA_PROMPT } from '@mastra/astra'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${ASTRA_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **libSQL**:
 
 ```ts
-import { LIBSQL_PROMPT } from "@mastra/libsql";
+import { LIBSQL_PROMPT } from '@mastra/libsql'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${LIBSQL_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **Upstash**:
 
 ```ts
-import { UPSTASH_PROMPT } from "@mastra/upstash";
+import { UPSTASH_PROMPT } from '@mastra/upstash'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${UPSTASH_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **Vectorize**:
 
 ```ts
-import { VECTORIZE_PROMPT } from "@mastra/vectorize";
+import { VECTORIZE_PROMPT } from '@mastra/vectorize'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${VECTORIZE_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **MongoDB**:
 
 ```ts
-import { MONGODB_PROMPT } from "@mastra/mongodb";
+import { MONGODB_PROMPT } from '@mastra/mongodb'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${MONGODB_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **OpenSearch**:
 
 ```ts
-import { OPENSEARCH_PROMPT } from "@mastra/opensearch";
+import { OPENSEARCH_PROMPT } from '@mastra/opensearch'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${OPENSEARCH_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 **S3Vectors**:
 
 ```ts
-import { S3VECTORS_PROMPT } from "@mastra/s3vectors";
+import { S3VECTORS_PROMPT } from '@mastra/s3vectors'
 
 export const ragAgent = new Agent({
-  id: "rag-agent",
-  name: "RAG Agent",
-  model: "openai/gpt-5.1",
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.4',
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${S3VECTORS_PROMPT}
   `,
   tools: { vectorQueryTool },
-});
+})
 ```
 
 ### Re-ranking
@@ -465,20 +462,20 @@ Initial vector similarity search can sometimes miss nuanced relevance. Re-rankin
 Here's how to use re-ranking:
 
 ```ts
-import {
-  rerankWithScorer as rerank,
-  MastraAgentRelevanceScorer
-} from "@mastra/rag";
+import { rerankWithScorer as rerank, MastraAgentRelevanceScorer } from '@mastra/rag'
 
 // Get initial results from vector search
 const initialResults = await pgVector.query({
-  indexName: "embeddings",
+  indexName: 'embeddings',
   queryVector: queryEmbedding,
   topK: 10,
-});
+})
 
 // Create a relevance scorer
-const relevanceProvider = new MastraAgentRelevanceScorer('relevance-scorer', "openai/gpt-5.1");
+const relevanceProvider = new MastraAgentRelevanceScorer(
+  'relevance-scorer',
+  'openai/gpt-5.4',
+)
 
 // Re-rank the results
 const rerankedResults = await rerank({
@@ -493,7 +490,7 @@ const rerankedResults = await rerank({
     },
     topK: 10,
   },
-);
+})
 ```
 
 The weights control how different factors influence the final ranking:
@@ -507,11 +504,11 @@ The weights control how different factors influence the final ranking:
 You can also use other relevance score providers like Cohere or ZeroEntropy:
 
 ```ts
-const relevanceProvider = new CohereRelevanceScorer("rerank-v3.5");
+const relevanceProvider = new CohereRelevanceScorer('rerank-v3.5')
 ```
 
 ```ts
-const relevanceProvider = new ZeroEntropyRelevanceScorer("zerank-1");
+const relevanceProvider = new ZeroEntropyRelevanceScorer('zerank-1')
 ```
 
 The re-ranked results combine vector similarity with semantic understanding to improve retrieval quality.