@mastra/rag 2.0.0-beta.3 → 2.0.0-beta.5

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @mastra/rag
 
+## 2.0.0-beta.5
+
+### Minor Changes
+
+- Add dynamic vectorStore resolver support for multi-tenant applications ([#11542](https://github.com/mastra-ai/mastra/pull/11542))
+
+  The vectorStore option in createVectorQueryTool and createGraphRAGTool now accepts a resolver function in addition to static instances. This enables multi-tenant setups where each tenant has isolated data in separate PostgreSQL schemas.
+
+  Also improves providerOptions type safety by using MastraEmbeddingOptions types instead of a generic Record type.
+
+### Patch Changes
+
+- dependencies updates: ([#10133](https://github.com/mastra-ai/mastra/pull/10133))
+  - Updated dependency [`js-tiktoken@^1.0.21` ↗︎](https://www.npmjs.com/package/js-tiktoken/v/1.0.21) (from `^1.0.20`, in `dependencies`)
+
+- Add embedded documentation support for Mastra packages ([#11472](https://github.com/mastra-ai/mastra/pull/11472))
+
+  Mastra packages now include embedded documentation in the published npm package under `dist/docs/`. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from `node_modules`.
+
+  Each package includes:
+  - **SKILL.md** - Entry point explaining the package's purpose and capabilities
+  - **SOURCE_MAP.json** - Machine-readable index mapping exports to types and implementation files
+  - **Topic folders** - Conceptual documentation organized by feature area
+
+  Documentation is driven by the `packages` frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.
+
+- Updated dependencies [[`d2d3e22`](https://github.com/mastra-ai/mastra/commit/d2d3e22a419ee243f8812a84e3453dd44365ecb0), [`bc72b52`](https://github.com/mastra-ai/mastra/commit/bc72b529ee4478fe89ecd85a8be47ce0127b82a0), [`05b8bee`](https://github.com/mastra-ai/mastra/commit/05b8bee9e50e6c2a4a2bf210eca25ee212ca24fa), [`c042bd0`](https://github.com/mastra-ai/mastra/commit/c042bd0b743e0e86199d0cb83344ca7690e34a9c), [`940a2b2`](https://github.com/mastra-ai/mastra/commit/940a2b27480626ed7e74f55806dcd2181c1dd0c2), [`e0941c3`](https://github.com/mastra-ai/mastra/commit/e0941c3d7fc75695d5d258e7008fd5d6e650800c), [`0c0580a`](https://github.com/mastra-ai/mastra/commit/0c0580a42f697cd2a7d5973f25bfe7da9055038a), [`28f5f89`](https://github.com/mastra-ai/mastra/commit/28f5f89705f2409921e3c45178796c0e0d0bbb64), [`e601b27`](https://github.com/mastra-ai/mastra/commit/e601b272c70f3a5ecca610373aa6223012704892), [`3d3366f`](https://github.com/mastra-ai/mastra/commit/3d3366f31683e7137d126a3a57174a222c5801fb), [`5a4953f`](https://github.com/mastra-ai/mastra/commit/5a4953f7d25bb15ca31ed16038092a39cb3f98b3), [`eb9e522`](https://github.com/mastra-ai/mastra/commit/eb9e522ce3070a405e5b949b7bf5609ca51d7fe2), [`20e6f19`](https://github.com/mastra-ai/mastra/commit/20e6f1971d51d3ff6dd7accad8aaaae826d540ed), [`4f0b3c6`](https://github.com/mastra-ai/mastra/commit/4f0b3c66f196c06448487f680ccbb614d281e2f7), [`74c4f22`](https://github.com/mastra-ai/mastra/commit/74c4f22ed4c71e72598eacc346ba95cdbc00294f), [`81b6a8f`](https://github.com/mastra-ai/mastra/commit/81b6a8ff79f49a7549d15d66624ac1a0b8f5f971), [`e4d366a`](https://github.com/mastra-ai/mastra/commit/e4d366aeb500371dd4210d6aa8361a4c21d87034), [`a4f010b`](https://github.com/mastra-ai/mastra/commit/a4f010b22e4355a5fdee70a1fe0f6e4a692cc29e), [`73b0bb3`](https://github.com/mastra-ai/mastra/commit/73b0bb394dba7c9482eb467a97ab283dbc0ef4db), [`5627a8c`](https://github.com/mastra-ai/mastra/commit/5627a8c6dc11fe3711b3fa7a6ffd6eb34100a306), [`3ff45d1`](https://github.com/mastra-ai/mastra/commit/3ff45d10e0c80c5335a957ab563da72feb623520), [`251df45`](https://github.com/mastra-ai/mastra/commit/251df4531407dfa46d805feb40ff3fb49769f455), [`f894d14`](https://github.com/mastra-ai/mastra/commit/f894d148946629af7b1f452d65a9cf864cec3765), [`c2b9547`](https://github.com/mastra-ai/mastra/commit/c2b9547bf435f56339f23625a743b2147ab1c7a6), [`580b592`](https://github.com/mastra-ai/mastra/commit/580b5927afc82fe460dfdf9a38a902511b6b7e7f), [`58e3931`](https://github.com/mastra-ai/mastra/commit/58e3931af9baa5921688566210f00fb0c10479fa), [`08bb631`](https://github.com/mastra-ai/mastra/commit/08bb631ae2b14684b2678e3549d0b399a6f0561e), [`4fba91b`](https://github.com/mastra-ai/mastra/commit/4fba91bec7c95911dc28e369437596b152b04cd0), [`12b0cc4`](https://github.com/mastra-ai/mastra/commit/12b0cc4077d886b1a552637dedb70a7ade93528c)]:
+  - @mastra/core@1.0.0-beta.20
+
+## 2.0.0-beta.4
+
+### Patch Changes
+
+- Add support for AI SDK v6 (LanguageModelV3) ([#11191](https://github.com/mastra-ai/mastra/pull/11191))
+
+  Agents can now use `LanguageModelV3` models from AI SDK v6 beta providers like `@ai-sdk/openai@^3.0.0-beta`.
+
+  **New features:**
+  - Usage normalization: V3's nested usage format is normalized to Mastra's flat format with `reasoningTokens`, `cachedInputTokens`, and raw data preserved in a `raw` field
+
+  **Backward compatible:** All existing V1 and V2 models continue to work unchanged.
+
+- Updated dependencies [[`4f94ed8`](https://github.com/mastra-ai/mastra/commit/4f94ed8177abfde3ec536e3574883e075423350c), [`ac3cc23`](https://github.com/mastra-ai/mastra/commit/ac3cc2397d1966bc0fc2736a223abc449d3c7719), [`a86f4df`](https://github.com/mastra-ai/mastra/commit/a86f4df0407311e0d2ea49b9a541f0938810d6a9), [`029540c`](https://github.com/mastra-ai/mastra/commit/029540ca1e582fc2dd8d288ecd4a9b0f31a954ef), [`66741d1`](https://github.com/mastra-ai/mastra/commit/66741d1a99c4f42cf23a16109939e8348ac6852e), [`01b20fe`](https://github.com/mastra-ai/mastra/commit/01b20fefb7c67c2b7d79417598ef4e60256d1225), [`0dbf199`](https://github.com/mastra-ai/mastra/commit/0dbf199110f22192ce5c95b1c8148d4872b4d119), [`a7ce182`](https://github.com/mastra-ai/mastra/commit/a7ce1822a8785ce45d62dd5c911af465e144f7d7)]:
+  - @mastra/core@1.0.0-beta.14
+
 ## 2.0.0-beta.3
 
 ### Patch Changes

package/dist/docs/README.md

@@ -0,0 +1,32 @@
+# @mastra/rag Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── rag/ (11 files)
+├── tools/ (3 files)
+```
+
+## Version
+
+Package: @mastra/rag
+Version: 2.0.0-beta.5

package/dist/docs/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mastra-rag-docs
+description: Documentation for @mastra/rag. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/rag Documentation
+
+> **Version**: 2.0.0-beta.5
+> **Package**: @mastra/rag
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Rag](rag/) - 11 file(s)
+- [Tools](tools/) - 3 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "2.0.0-beta.5",
+  "package": "@mastra/rag",
+  "exports": {},
+  "modules": {}
+}

package/dist/docs/rag/01-overview.md

@@ -0,0 +1,74 @@
+> 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
+import { embedMany } from "ai";
+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
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
+const { embeddings } = await embedMany({
+  values: chunks.map((chunk) => chunk.text),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small")
+});
+
+// 4. Store in vector database
+const pgVector = new PgVector({
+  id: 'pg-vector',
+  connectionString: 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).
+
+## Vector Storage
+
+Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](./vector-databases).
+
+## More resources
+
+- [Chain of Thought RAG Example](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/cot-rag)

package/dist/docs/rag/02-chunking-and-embedding.md

@@ -0,0 +1,190 @@
+> Guide on chunking and embedding documents in Mastra for efficient processing and retrieval.
+
+# Chunking and Embedding Documents
+
+Before processing, create a MDocument instance from your content. You can initialize it from various formats:
+
+```ts
+const docFromText = MDocument.fromText("Your plain text content...");
+const docFromHTML = MDocument.fromHTML("<html>Your HTML content...</html>");
+const docFromMarkdown = MDocument.fromMarkdown("# Your Markdown content...");
+const docFromJSON = MDocument.fromJSON(`{ "key": "value" }`);
+```
+
+## Step 1: Document Processing
+
+Use `chunk` to split documents into manageable pieces. Mastra supports multiple chunking strategies optimized for different document types:
+
+- `recursive`: Smart splitting based on content structure
+- `character`: Simple character-based splits
+- `token`: Token-aware splitting
+- `markdown`: Markdown-aware splitting
+- `semantic-markdown`: Markdown splitting based on related header families
+- `html`: HTML structure-aware splitting
+- `json`: JSON structure-aware splitting
+- `latex`: LaTeX structure-aware splitting
+- `sentence`: Sentence-aware splitting
+
+> **Note:**
+Each strategy accepts different parameters optimized for its chunking approach.
+
+Here's an example of how to use the `recursive` strategy:
+
+```ts
+const chunks = await doc.chunk({
+  strategy: "recursive",
+  maxSize: 512,
+  overlap: 50,
+  separators: ["\n"],
+  extract: {
+    metadata: true, // Optionally extract metadata
+  },
+});
+```
+
+For text where preserving sentence structure is important, here's an example of how to use the `sentence` strategy:
+
+```ts
+const chunks = await doc.chunk({
+  strategy: "sentence",
+  maxSize: 450,
+  minSize: 50,
+  overlap: 0,
+  sentenceEnders: ["."],
+  keepSeparator: true,
+});
+```
+
+For markdown documents where preserving the semantic relationships between sections is important, here's an example of how to use the `semantic-markdown` strategy:
+
+```ts
+const chunks = await doc.chunk({
+  strategy: "semantic-markdown",
+  joinThreshold: 500,
+  modelName: "gpt-3.5-turbo",
+});
+```
+
+> **Note:**
+Metadata extraction may use LLM calls, so ensure your API key is set.
+
+We go deeper into chunking strategies in our [`chunk()` reference documentation](https://mastra.ai/reference/v1/rag/chunk).
+
+## Step 2: Embedding Generation
+
+Transform chunks into embeddings using your preferred provider. Mastra supports embedding models through the model router.
+
+### Using the Model Router
+
+The simplest way is to use Mastra's model router with `provider/model` strings:
+
+```ts
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+import { embedMany } from "ai";
+
+const { embeddings } = await embedMany({
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  values: chunks.map((chunk) => chunk.text),
+});
+```
+
+Mastra supports OpenAI and Google embedding models. For a complete list of supported embedding models, see the [embeddings reference](https://mastra.ai/reference/v1/rag/embeddings).
+
+The model router automatically handles API key detection from environment variables.
+
+The embedding functions return vectors, arrays of numbers representing the semantic meaning of your text, ready for similarity searches in your vector database.
+
+### Configuring Embedding Dimensions
+
+Embedding models typically output vectors with a fixed number of dimensions (e.g., 1536 for OpenAI's `text-embedding-3-small`).
+Some models support reducing this dimensionality, which can help:
+
+- Decrease storage requirements in vector databases
+- Reduce computational costs for similarity searches
+
+Here are some supported models:
+
+OpenAI (text-embedding-3 models):
+
+```ts
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
+const { embeddings } = await embedMany({
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  options: {
+    dimensions: 256, // Only supported in text-embedding-3 and later
+  },
+  values: chunks.map((chunk) => chunk.text),
+});
+```
+
+Google (text-embedding-001):
+
+```ts
+const { embeddings } = await embedMany({
+  model: "google/gemini-embedding-001", {
+    outputDimensionality: 256, // Truncates excessive values from the end
+  }),
+  values: chunks.map((chunk) => chunk.text),
+});
+```
+
+important[Vector Database Compatibility]
+When storing embeddings, the vector database index must be configured to match the output size of your embedding model. If the dimensions do not match, you may get errors or data corruption.
+
+## Example: Complete Pipeline
+
+Here's an example showing document processing and embedding generation with both providers:
+
+```ts
+import { embedMany } from "ai";
+
+import { MDocument } from "@mastra/rag";
+
+// Initialize document
+const doc = MDocument.fromText(`
+  Climate change poses significant challenges to global agriculture.
+  Rising temperatures and changing precipitation patterns affect crop yields.
+`);
+
+// Create chunks
+const chunks = await doc.chunk({
+  strategy: "recursive",
+  maxSize: 256,
+  overlap: 50,
+});
+
+// Generate embeddings with OpenAI
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
+const { embeddings } = await embedMany({
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  values: chunks.map((chunk) => chunk.text),
+});
+
+// OR
+
+// Generate embeddings with Cohere
+const { embeddings } = await embedMany({
+  model: "cohere/embed-english-v3.0",
+  values: chunks.map((chunk) => chunk.text),
+});
+
+// Store embeddings in your vector database
+await vectorStore.upsert({
+  indexName: "embeddings",
+  vectors: embeddings,
+});
+```
+
+##
+
+For more examples of different chunking strategies and embedding configurations, see:
+
+- [Chunk Reference](https://mastra.ai/reference/v1/rag/chunk)
+- [Embeddings Reference](https://mastra.ai/reference/v1/rag/embeddings)
+
+For more details on vector databases and embeddings, see:
+
+- [Vector Databases](./vector-databases)
+- [Embedding API Reference](https://mastra.ai/reference/v1/rag/embeddings)