@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/guides/guide/research-assistant.md

@@ -0,0 +1,348 @@
+# Building a Research Paper Assistant with RAG
+
+In this guide, you'll create an AI research assistant that can analyze academic papers and answer specific questions about their content using Retrieval Augmented Generation (RAG).
+
+You'll use the foundational Transformer paper ["Attention Is All You Need"](https://arxiv.org/html/1706.03762) as your example. As a database you'll use a local libSQL database.
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- An API key from a supported [Model Provider](https://mastra.ai/models)
+- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
+
+## How RAG works
+
+Let's understand how RAG works and how you'll implement each component.
+
+### Knowledge Store/Index
+
+- Converting text into vector representations
+- Creating numerical representations of content
+- **Implementation**: You'll use OpenAI's `text-embedding-3-small` to create embeddings and store them in LibSQLVector
+
+### Retriever
+
+- Finding relevant content via similarity search
+- Matching query embeddings with stored vectors
+- **Implementation**: You'll use LibSQLVector to perform similarity searches on the stored embeddings
+
+### Generator
+
+- Processing retrieved content with an LLM
+- Creating contextually informed responses
+- **Implementation**: You'll use GPT-4o-mini to generate answers based on retrieved content
+
+Your implementation will:
+
+1. Process the Transformer paper into embeddings
+2. Store them in LibSQLVector for quick retrieval
+3. Use similarity search to find relevant sections
+4. Generate accurate responses using retrieved context
+
+## Creating the Agent
+
+Let's define the agent's behavior, connect it to your Mastra project, and create the vector store.
+
+1. Install additional dependencies
+
+   After running the [installation guide](https://mastra.ai/guides/getting-started/quickstart) you'll need to install additional dependencies:
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/rag@latest ai
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/rag@latest ai
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/rag@latest ai
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/rag@latest ai
+   ```
+
+2. Now you'll create your RAG-enabled research assistant. The agent uses:
+
+   - A [Vector Query Tool](https://mastra.ai/reference/tools/vector-query-tool) for performing semantic search over the vector store to find relevant content in papers
+   - GPT-4o-mini for understanding queries and generating responses
+   - Custom instructions that guide the agent on how to analyze papers, use retrieved content effectively, and acknowledge limitations
+
+   Create a new file `src/mastra/agents/researchAgent.ts` and define your agent:
+
+   ```ts
+   import { Agent } from '@mastra/core/agent'
+   import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+   import { createVectorQueryTool } from '@mastra/rag'
+
+   // Create a tool for semantic search over the paper embeddings
+   const vectorQueryTool = createVectorQueryTool({
+     vectorStoreName: 'libSqlVector',
+     indexName: 'papers',
+     model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+   })
+
+   export const researchAgent = new Agent({
+     id: 'research-agent',
+     name: 'Research Assistant',
+     instructions: `You are a helpful research assistant that analyzes academic papers and technical documents.
+       Use the provided vector query tool to find relevant information from your knowledge base,
+       and provide accurate, well-supported answers based on the retrieved content.
+       Focus on the specific content available in the tool and acknowledge if you cannot find sufficient information to answer a question.
+       Base your responses only on the content provided, not on general knowledge.`,
+     model: 'openai/gpt-5.1',
+     tools: {
+       vectorQueryTool,
+     },
+   })
+   ```
+
+3. In the root of your project, grab the absolute path with the `pwd` command. The path might be similar to this:
+
+   ```bash
+   > pwd
+   /Users/your-name/guides/research-assistant
+   ```
+
+   In your `src/mastra/index.ts` file, add the following to your existing file and configuration:
+
+   ```ts
+   import { Mastra } from '@mastra/core'
+   import { LibSQLVector } from '@mastra/libsql'
+
+   const libSqlVector = new LibSQLVector({
+     id: 'research-vectors',
+     url: 'file:/Users/your-name/guides/research-assistant/vector.db',
+   })
+
+   export const mastra = new Mastra({
+     vectors: { libSqlVector },
+   })
+   ```
+
+   For the `url` use the absolute path you got from the `pwd` command. This way the `vector.db` file is created at the root of your project.
+
+   > **Note:** For the purpose of this guide you are using a hardcoded absolute path to your local libSQL file, however for production usage this won't work. You should use a remote persistent database then.
+
+4. In the `src/mastra/index.ts` file, add the agent to Mastra:
+
+   ```ts
+   import { Mastra } from '@mastra/core'
+   import { LibSQLVector } from '@mastra/libsql'
+   import { researchAgent } from './agents/researchAgent'
+
+   const libSqlVector = new LibSQLVector({
+     id: 'research-vectors',
+     url: 'file:/Users/your-name/guides/research-assistant/vector.db',
+   })
+
+   export const mastra = new Mastra({
+     agents: { researchAgent },
+     vectors: { libSqlVector },
+   })
+   ```
+
+## Processing documents
+
+In the following steps you'll fetch the research paper, split it into smaller chunks, generate embeddings for them, and store these chunks of information into the vector database.
+
+1. In this step the research paper is retrieved by providing an URL, then converted to a document object, and split into smaller, manageable chunks. By splitting into chunks the processing is faster and more efficient.
+
+   Create a new file `src/store.ts` and add the following:
+
+   ```ts
+   import { MDocument } from '@mastra/rag'
+
+   // Load the paper
+   const paperUrl = 'https://arxiv.org/html/1706.03762'
+   const response = await fetch(paperUrl)
+   const paperText = await response.text()
+
+   // Create document and chunk it
+   const doc = MDocument.fromText(paperText)
+   const chunks = await doc.chunk({
+     strategy: 'recursive',
+     maxSize: 512,
+     overlap: 50,
+     separators: ['\n\n', '\n', ' '],
+   })
+
+   console.log('Number of chunks:', chunks.length)
+   ```
+
+   Run the file in your terminal:
+
+   ```bash
+   npx bun src/store.ts
+   ```
+
+   You should get back this response:
+
+   ```bash
+   Number of chunks: 892
+   ```
+
+2. Finally, you'll prepare the content for RAG by:
+
+   1. Generating embeddings for each chunk of text
+   2. Creating a vector store index to hold the embeddings
+   3. Storing both the embeddings and metadata (original text and source information) in the vector database
+
+   > **Note:** This metadata is crucial as it allows for returning the actual content when the vector store finds relevant matches.
+
+   This allows the agent to efficiently search and retrieve relevant information.
+
+   Open the `src/store.ts` file and add the following:
+
+   ```ts
+   import { MDocument } from '@mastra/rag'
+   import { embedMany } from 'ai'
+   import { mastra } from './mastra'
+
+   // Load the paper
+   const paperUrl = 'https://arxiv.org/html/1706.03762'
+   const response = await fetch(paperUrl)
+   const paperText = await response.text()
+
+   // Create document and chunk it
+   const doc = MDocument.fromText(paperText)
+   const chunks = await doc.chunk({
+     strategy: 'recursive',
+     maxSize: 512,
+     overlap: 50,
+     separators: ['\n\n', '\n', ' '],
+   })
+
+   // Generate embeddings
+   const { embeddings } = await embedMany({
+     model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+     values: chunks.map(chunk => chunk.text),
+   })
+
+   // Get the vector store instance from Mastra
+   const vectorStore = mastra.getVector('libSqlVector')
+
+   // Create an index for paper chunks
+   await vectorStore.createIndex({
+     indexName: 'papers',
+     dimension: 1536,
+   })
+
+   // Store embeddings
+   await vectorStore.upsert({
+     indexName: 'papers',
+     vectors: embeddings,
+     metadata: chunks.map(chunk => ({
+       text: chunk.text,
+       source: 'transformer-paper',
+     })),
+   })
+   ```
+
+   Lastly, you'll now need to store the embeddings by running the script again:
+
+   ```bash
+   npx bun src/store.ts
+   ```
+
+   If the operation was successful you should see no output/errors in your terminal.
+
+## Test the Assistant
+
+Now that the vector database has all embeddings, you can test the research assistant with different types of queries.
+
+Create a new file `src/ask-agent.ts` and add different types of queries:
+
+```ts
+import { mastra } from './mastra'
+const agent = mastra.getAgent('researchAgent')
+
+// Basic query about concepts
+const query1 = 'What problems does sequence modeling face with neural networks?'
+const response1 = await agent.generate(query1)
+console.log('\nQuery:', query1)
+console.log('Response:', response1.text)
+```
+
+Run the script:
+
+```bash
+npx bun src/ask-agent.ts
+```
+
+You should see output like:
+
+```bash
+Query: What problems does sequence modeling face with neural networks?
+Response: Sequence modeling with neural networks faces several key challenges:
+1. Vanishing and exploding gradients during training, especially with long sequences
+2. Difficulty handling long-term dependencies in the input
+3. Limited computational efficiency due to sequential processing
+4. Challenges in parallelizing computations, resulting in longer training times
+```
+
+Try another question:
+
+```ts
+import { mastra } from './mastra'
+const agent = mastra.getAgent('researchAgent')
+
+// Query about specific findings
+const query2 = 'What improvements were achieved in translation quality?'
+const response2 = await agent.generate(query2)
+console.log('\nQuery:', query2)
+console.log('Response:', response2.text)
+```
+
+Output:
+
+```text
+Query: What improvements were achieved in translation quality?
+Response: The model showed significant improvements in translation quality, achieving more than 2.0
+BLEU points improvement over previously reported models on the WMT 2014 English-to-German translation
+task, while also reducing training costs.
+```
+
+### Serve the Application
+
+Start the Mastra server to expose your research assistant via API:
+
+```bash
+mastra dev
+```
+
+Your research assistant will be available at:
+
+```text
+http://localhost:4111/api/agents/researchAgent/generate
+```
+
+Test with curl:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/researchAgent/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      { "role": "user", "content": "What were the main findings about model parallelization?" }
+    ]
+  }'
+```
+
+## Advanced RAG Examples
+
+Explore these examples for more advanced RAG techniques:
+
+- [Filter RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag) for filtering results using metadata
+- [Cleanup RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/cleanup-rag) for optimizing information density
+- [Chain of Thought RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/cot-rag) for complex reasoning queries using workflows
+- [Rerank RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/rerank-rag) for improved result relevance